3 git-debrebase - git data model for Debian packaging
7 git-debrebase is a tool for representing in git,
9 Debian packages based on upstream source code.
12 has a fast forwarding history.
13 The delta queue (changes to upstream files) is represented
14 as a series of individual git commits,
15 which can worked on with rebase,
18 git-debrebase is designed to work well with dgit.
19 git-debrebase can also be used in workflows without source packages,
20 for example to work on Debian-format packages outside or alongside Debian.
22 git-debrebase is not very suitable for use by Debian derivatives,
23 to work on packages inherited from Debian,
24 because it assumes that you want to throw away any packaging
25 provided by your upstream.
29 ------/--A!----/--B3!--%--/--> interchange view
30 / / / with debian/ directory
31 % % % entire delta queue applied
32 / / / 3.0 (quilt) has debian/patches
37 1 1 1 breakwater branch, merging baseline
38 / / / unmodified upstream code
39 ---@-----@--A----@--B--C plus debian/ (but no debian/patches)
40 / / / no ref refers to this: we
41 --#-----#-------#-----> upstream reconstruct its identity by
42 inspecting interchange branch
45 1,2,3 commits touching upstream files only
46 A,B,C commits touching debian/ only
47 B3 mixed commit (eg made by an NMUer)
50 -@- anchor merge, takes contents of debian/ from the
51 / previous `breakwater' commit and rest from upstream
53 -/- pseudomerge; contents are identical to
54 / parent lower on diagram.
56 % dgit-generated commit of debian/patches.
57 `3.0 (quilt)' only; generally dropped by git-debrebase.
59 * Maintainer's HEAD was here while they were editing,
60 before they said they were done, at which point their
61 tools made -/- (and maybe %) to convert to
62 the fast-forwarding interchange branch.
64 ! NMUer's HEAD was here when they said `dgit push'.
65 Rebase branch launderer turns each ! into an
68 =head1 BRANCHES AND BRANCH STATES
70 git-debrebase has one primary branch,
71 the B<interchange branch>.
72 This branch is found on Debian contributor's workstations
73 (typically, a maintainer would call it B<master>),
74 in the Debian dgit git server as the suite branch (B<dgit/dgit/sid>)
75 and on other git servers which support Debian work
76 (eg B<master> on salsa).
78 The interchange branch is fast-forwarding
79 (by virtue of pseudomerges, where necessary).
81 It is possible to have multiple different interchange branches
83 stored as different local and remote git branches.
84 However, divergence should be avoided where possible -
87 A suitable interchange branch can be used directly with dgit.
88 In this case each dgit archive suite branch is a separate
91 Within the ancestry of the interchange branch,
92 there is another important, implicit branch, the
94 The breakwater contains unmodified upstream source,
95 but with Debian's packaging superimposed
96 (replacing any C<debian/> directory that may be in upstream).
97 The breakwater does not contain any representation of
99 The part of the breakwater processed by git-debrebase
100 is the part since the most reecent B<anchor>,
101 which is usually a special merge generated by git-debrebase.
103 When working, locally,
104 the user's branch can be in a rebasing state,
105 known as B<unstitched>.
106 While a branch is unstitched,
107 its previous tip is recorded,
108 so that the previous history
111 stitched into the fast-forwarding interchange form.
113 An unstitched branch may be in
116 which means it has a more particular special form
117 convenient for manipulating the delta queue.
119 =head1 BRANCH CONTENTS
121 It is most convenient to describe the
124 It contains B<in this order> (ancestors first):
131 which is usually a special two-parent merge:
133 a previous branch tip with Debian packaging tip
134 (perhaps a previous breakwater tip)
135 whose upstream files are irrelevant,
136 and whose packaging files are identical to the anchor's.
137 The second parent is an upstream source commit,
138 whose packaging files (if any) are irrelevant,
139 and whose upstream files are identical to the anchor's.
140 Anchor merges always contain
141 C<[git-debrebase anchor: ...]>
142 as a line in the commit message.
144 an anchor may be a single-parent commit which introduces
145 the C<debian/> directory and makes no other changes:
146 ie, the start of Debian packaging.
150 Zero or more single-parent commits
151 containing only packaging changes.
152 (And no quilt patch changes.)
154 =item Delta queue commits
156 Zero or more single-parent commits
157 contaioning only changes to upstream files.
164 branch state is the same,
165 except that it may contain,
171 =item Linear commits to the source
173 Further commit(s) containing changes to
177 possibly mixed within a single commit.
178 (But not quilt patch changes.)
180 =item Quilt patch addition for `3.0 (quilt)'
182 Commit(s) which add patches to B<debian/patches/>,
183 and add those patches to the end of B<series>.
184 These are only necessary when working with
185 packages in C<.dsc 3.0 (quilt)> format.
186 For git-debrebase they are purely an output;
187 they are deleted when branches are laundered.
193 branch state is the same, but may additionally contain
195 possibly intermixed with the extra commits
196 which may be found on an unstitched unlaundered branch):
200 =item Pseudomerge to make fast forward
202 A pseudomerge making the branch fast forward from
204 The contributing parent is itself in interchange format.
205 Normally the overwritten parent is
206 a previous tip of the interchange branch,
207 but this is not necessary as the overwritten
208 parent is not examined.
210 If the two parents have identical trees,
211 the contributing parent is taken to be
212 the one with the later commit date,
213 or if the commit dates are the same,
216 =item dgit dsc import
218 Debian .dsc source package import(s) made by dgit.
219 Each such import must be a two-parent pseudomerge
220 whose contributing parent is in the special
221 dgit format (not described further here).
222 The overwritten parent must be
223 the previous interchange tip.
224 This is the form normally generated by dgit
225 when it imports .dsc-based uploads.
229 =head1 STITCHING, PSEUDO-MERGES, FFQ RECORD
231 Whenever the branch C<refs/B> is unstitched,
232 the previous tip is recorded in the git ref C<refs/ffq-prev/B>.
234 Unstiched branches are not fast forward from the published
235 interchange branches [1].
236 So before a branch can be pushed,
237 the right pseudomerge must be reestablished.
238 This is the stitch operation,
239 which consumes the ffq-prev ref.
241 When the user has an unstitched branch,
242 they may rewrite it freely,
243 from the breakwater tip onwards.
244 Such a git rebase is the default operation for git-debrebase.
245 Rebases should not go back before the breakwater tip,
246 and certainly not before the most recent anchor.
248 Unstitched branches must not be pushed to interchange branch refs
249 (by the use of C<git push -f> or equivalent).
250 It is OK to share an unstitched branch
251 in similar circumstances and with similar warnings
252 to sharing any other rebasing git branch.
254 [1] Strictly, for a package
255 which has never had a Debian delta queue,
256 the interchange and breakwater branches may be identical,
257 in which case the unstitched branch is fast forward
258 from the interchange branch and no pseudomerge is needed.
260 When ffq-prev is not present,
261 C<refs/debrebase-last/B> records some ancestor of refs/B,
262 (usually, the result of last stitch).
263 This can be used to quickly determine whether refs/B
264 is being maintained in git-debrebase form.
268 Note that the representation described here does not permit
269 general merges on any of the relevant branches.
270 For this reason the tools will try to help the user
271 avoid divergence of the interchange branch.
273 Automatic resolution of divergent interchange branches
274 (or laundering of merges on the interchange branch)
275 is thought to be possible,
276 but there is no tooling for this yet:
278 Nonlinear (merging) history in the interchange branch is awkward
279 because it (obviously) does not preserve
280 the linearity of the delta queue.
281 Easy merging of divergent delta queues is a research problem.
283 Nonlinear (merging) history in the breakwater branch is
284 in principle tolerable,
285 but each of the parents would have to be, in turn,
287 and difficult qeustions arise if they don't have the same anchor.
289 We use the commit message annotation to
290 distinguish the special anchor merges from other general merges,
291 so we can at least detect unsupported merges.
293 =head1 LEGAL OPERATIONS
295 The following basic operations follows from this model
296 (refer to the diagram above):
300 =item Append linear commits
302 No matter the branch state,
303 it is always fine to simply git commit
304 (or cherry-pick etc.)
305 commits containing upstream file changes, packaging changes,
308 (This may make the branch unlaundered.)
312 Record the previous tip in ffq-prev,
313 if we were stitched before
314 (and delete debrebase-last).
316 Reorganise the current branch so that the packaging
318 followed by the delta queue,
319 turning C<-@-A-1-2-B3> into C<...@-A-B-1-2-3>.
321 Drop pseudomerges and any quilt patches.
323 =item Interactive rebase
325 With a laundered branch,
326 one can do an interactive git rebase of the delta queue.
328 =item New upstream rebase
330 Start rebasing onto a new upstream version,
331 turning C<...#..@-A-B-1-2-3> into C<(...#..@-A-B-|...#'-)@'-1-2>.
333 This has to be a wrapper around git-rebase,
334 which prepares @' and then tries to rebase 1 2 onto @'.
335 If the user asks for an interactive rebase,
336 @' doesn't appear in the commit list.
338 Note that the construction of @' cannot fail
339 because @' simply copies debian/ from B and and everything else from #'.
340 (Rebasing A and B is undesirable.
341 We want the debian/ files to be non-rebasing
342 so that git log shows the packaging history.)
347 whose contributing parent to is the unstitched branch
349 whose overwritten parent is ffq-prev,
350 consuming ffq-prev in the process
351 (and writing debrebase-last instead).
352 Ideally the contributing parent would be a laundered branch,
353 or perhaps a laundered branch with a quilt patch addition commit.
355 =item Commit quilt patches
357 To generate a tree which can be represented as a
358 3.0 (quilt) .dsc source packages,
359 the delta queue must be reified inside the git tree
360 in B<debian/patches/>.
361 These patch files can be stripped out and/or regenerated as needed.
365 =head1 COMMIT MESSAGE ANNOTATIONS
367 git-debrebase makes annotations
368 in the messages of commits it generates.
372 [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
374 git-debrebase does not pay attention to anything after the colon,
377 The full set of annotations is:
378 [git-debrebase: split mixed commit, debian part]
379 [git-debrebase: split mixed commit, upstream-part]
380 [git-debrebase: convert dgit import, debian changes]
381 [git-debrebase anchor: convert dgit import, upstream changes]
383 [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
384 [git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge]
385 [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
387 [git-debrebase convert-from-gbp: drop patches]
388 [git-debrebase anchor: declare upstream]
389 [git-debrebase pseudomerge: stitch]
391 [git-debrebase convert-to-gbp: commit patches]
393 Only anchor merges have the C<[git-debrebase anchor: ...]> tag.
394 Single-parent anchors are not generated by git-debrebase,
395 and when made manually should not be tagged.
397 The C<split mixed commit> and C<convert dgit import>
398 tags are added to the pre-existing commit message,
399 when git-debrebase rewrites the commit.
407 A merge which does not actually merge the trees;
408 instead, it takes its tree, by construction, from only one parent.
409 These are used to make a rewritten history fast forward
411 so that it can be pushed and pulled normally.
412 Manual construction of pseudomerges can be done with
414 but is not normally needed when using git-debrebase.
416 =item Packaging files
418 Files in the source tree within B<debian/>.
419 (Does not include anything which may exist in B<debian/patches/>.)
423 The version of the package without Debian's packaging.
424 Typically provided by the actual upstream project,
425 and often tracked by Debian contributors in a branch C<upstream>.
429 Files in the source tree outside B<debian/>.
430 These may include unmodified source from upstream,
431 but also files which have been modified or created for Debian.
435 Debian's changes to upstream files:
436 a series of git commits.
440 Files in B<debian/patches/> generated for the benefit of
441 dpkg-source's 3.0 (quilt) .dsc source package format.
442 Not used, and often deleted, by git-debrebase.
446 =head1 APPENDIX - DGIT IMPORT HANDLING
448 Consider a non-dgit NMU followed by a dgit NMU:
450 interchange --/--B3!--%--/----D*-->
463 --#--------> upstream
468 =XBC% dgit tarball import of .debian.tar.gz containing
469 Debian packaging including changes B C and quilt patches
471 0 dgit tarball import of upstream tarball
472 00 dgit tarball import of supplementary upstream tarball
473 &_ dgit nearly-breakwater import
474 &' git-debrebase converted import (upstream files only)
475 D' git-debrebase converted debian/ changes import
477 * ** before and after HEAD
479 We want to transform this into:
483 =item I. No new upstream version
486 --/--B3!--%--/------D*-------------/-->
497 --@--A-----B-----------------------C--D
499 --#----------------------------------------->
501 =item II. New upstream
505 --/--B3!--%--/------D*-------------/-->
516 --@--A-----B--------------------@--C--D
518 --#----------------------- - - / - - ----->
529 dgit-maint-rebase(7),