chiark / gitweb /
git-debrebase: introduce update_head_checkout
[dgit.git] / README.git-debrebase
1
2
3 My preferred answer is that it is a constantly rebasing branch topped
4 with a series of pseudomerges to make it fast-forwarding.
5
6            ------/--A!----/--B3!--%--/--> interchange view
7                 /        /          /      with debian/ directory
8                %        %          %       all upstream changes applied
9               /        /          /        3.0 (quilt) has debian/patches
10              /        /          3*
11             /        /          /
12            2*       2*         2
13           /        /          /
14          1        1          1    `breakwater' branch, merging baseline
15         /        /          /     unmodified upstream code
16     ---p-----p--A----p--B--C      plus debian/ (but no debian/patches)
17       /     /       /                     no ref refers to this: we
18    --#-----#-------#-----> upstream        reconstruct its identity by
19                                            inspecting interchange branch
20     Key:
21
22       1,2,3   commits touching upstream files only
23       A,B,C   commits touching debian/ only
24       B3      mixed commit (eg made by an NMUer)
25       #       upstream releases
26
27      -p-      special merge, takes contents of debian/ from the
28      /         previous `breakwater' commit and rest from upstream
29
30      -/-      pseudomerge; contents are identical to
31      /         parent lower on diagram.
32
33       %       dgit-generated commit of debian/patches.
34               `3.0 (quilt)' only; dropped by rebase tool.
35
36       *       Maintainer's HEAD was here while they were editing,
37               before they said they were done, at which point their
38               tools generated [% and] -/- commit[s] to convert to
39               the fast-forwarding interchange branch.  (Maybe the
40               tooling is simply `dgit push'.)
41
42       !       NMUer's HEAD was here when they said `dgit push'.
43               Rebase branch launderer turns each ! into an
44               equivalent *.
45
46
47 Looking from the tip of the interchange view, it is I think always
48 possible to classify these commits appropriately: pseudomerges are
49 fairly obvious (if all three trees are identical, we descend to the
50 parent with the most recent commit date), and the `p' special merge is
51 the only non-pseudo merge and has a special form.
52
53 So it would be possible to write a `git-debrebase' tool which would
54 take (for example) B4, above, and be able to perform functions like:
55
56  * Strip pseudomerges: Rewrite the current branch so it contains no
57    pseudomerges, turning ...B3 into ...p-A-1-2-B3.  (This should
58    make a note, in your .git/ somewhere, of the original branch
59    tip so that it can be overwritten with a pseudomerge.)
60
61  * Cleanup branch: Reorganise the current branch so that the debian/
62    changes come first, turning -p-A-1-2-B3 into ...p-A-B-1-2-3.
63
64  * New upstream rebase: Start rebasing onto a new upstream version,
65    turning ...#..p-A-B-1-2-3 into (...#..p-A-B-|...#'-)p'-1-2.  This
66    would be a wrapper around git-rebase, which prepares p' and then
67    tries to rebase 1 2 onto p'.  So if you ask for an interactive
68    rebase p' doesn't appear in your commit list.
69
70    Note that the construction of p' cannot fail because p' simply
71    copies debian/ from B and and everything else from #'.  (Rebasing A
72    and B is undesirable.  We want the debian/ files to be non-rebasing
73    so we can `git log' and get the packaging history.)
74
75  * Record pseudomerge.  This is like "committing" your patch queue.
76    The LH parent is taken from the previously recorded tip.  (We could
77    perhaps check that this is consistent with what we see in
78    debian/changelog, but that is not a sufficient check so the
79    recorded tip check is primary.)
80
81 Maybe some of these operations should automatically edit
82 debian/changelog.
83
84 The only thing that this can't easily do is permit nonlinear (ie,
85 merging) history on the `packaging-only' branch, because upstream
86 might contain debian/ files too, so it is not possible to distinguish
87 a merge of two `packaging-only' branches from the special merge `p'.
88 (Indeed I since upstream might copy debian/ from us, I think it is not
89 easy to reliably distinguish the two parents of a `p'.  In the most
90 exciting edge case, upstream might `git merge' a previous instance of
91 our interchange view, but I think even then everything still works.)
92
93 Sean Whitton writes ("Re: Feedback on 3.0 source format problems"):
94 >  Does the [breakwater] branch contain debian/ alone?
95
96 No, it also contains a complete unmodified copy of the upstream code.
97 (Except that if upstream had a debian/ directory, it is completely
98 replaced.)
99
100 For `3.0 (quilt)' the breakwater branch contains roughly what you
101 would get if you untarred the origs and the debian.tar.gz, and then
102 deleted all the patches without applying them.
103
104
105 dgit import handling
106 --------------------
107
108 Consider a non-dgit NMU followed by a dgit NMU:
109
110
111
112             interchange --/--B3!--%--/----D*-->
113                          /          /
114                         %          4
115                        /          3
116                       /          2
117                      /          1
118                     2*         &_
119                    /          /| \
120                   1          0 00 =XBC%
121                  /
122                 /
123           --p--A     breakwater
124            /
125         --#--------> upstream
126
127
128  Key:
129
130     =XBC%     dgit tarball import of .debian.tar.gz containing
131               Debian packaging including changes B C and patches
132
133     0         dgit tarball import of upstream tarball
134     00        dgit tarball import of supplementary upstream tarball
135     &_        dgit nearly-breakwater import
136     &'        git-debrebase converted import (upstream files only)
137     D'        git-debrebase converted debian/ changes import
138
139     * **      before and after HEAD
140
141 Want to transform this into:
142
143  I. No new upstream version (0 + 00 eq #)
144
145                         --/--B3!--%--/------D*-------------/-->
146                          /          /                     /
147                         %          4                     4**
148                        /          3                     3
149                       /          2                     2
150                      /          1                     1
151                     2*         &_                    /
152                    /          /| \                  /
153                   1          0 00 =XBC%            /
154                  /                                /
155                 /                                /
156           --p--A-----B-----------------------C--D
157            /
158         --#----------------------------------------->
159
160
161  II. New upstream (0 + 00 neq #)
162
163                         --/--B3!--%--/------D*-------------/-->
164                          /          /                     /
165                         %          4                     4**
166                        /          3                     3
167                       /          2                     2
168                      /          1                     1
169                     2*         &_                    /
170                    /          /| \                  /
171                   1          0 00 =XBC%            /
172                  /                                /
173                 /                                /
174           --p--A-----B--------------------p--C--D
175            /                             /
176         --#----------------------- - -  /  - - ----->
177                                        /
178                                       &'
179                                      /|
180                                     0 00