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.
23 itself is not very suitable for use by Debian derivatives,
24 to work on packages inherited from Debian,
25 because it assumes that you want to throw away any packaging
26 provided by your upstream.
27 However, of git-debrebase in Debian does not make anything harder for
28 derivatives, and it can make some things easier.
36 A merge which does not actually merge the trees;
37 instead, it takes its tree, by construction, from only one parent.
38 These are used to make a rewritten history fast forward
40 so that it can be pushed and pulled normally.
41 Manual construction of pseudomerges can be done with
43 but is not normally needed when using git-debrebase.
47 Files in the source tree within B<debian/>,
48 excluding anything in B<debian/patches/>.
52 The version of the package without Debian's packaging.
53 Typically provided by the actual upstream project,
54 and sometimes tracked by Debian contributors in a branch C<upstream>.
56 Upstream contains upstream files,
57 but some upstreams also contain packaging files in B<debian/>.
58 Any such non-upstream files found in upstream
59 are thrown away by git-debrebase
60 each time a new upstream version is incorporated.
64 Files in the source tree outside B<debian/>.
65 These may include unmodified source from upstream,
66 but also files which have been modified or created for Debian.
70 Debian's changes to upstream files:
71 a series of git commits.
75 Files in B<debian/patches/> generated for the benefit of
76 dpkg-source's 3.0 (quilt) .dsc source package format.
77 Not used, often deleted, and regenerated when needed,
84 ------/--A!----/--B3!--%--/--> interchange view
85 / / / with debian/ directory
86 % % % entire delta queue applied
87 / / / 3.0 (quilt) has debian/patches
88 / / 3* "master" on Debian git servers
92 1 1 1 breakwater branch, merging baseline
93 / / / unmodified upstream code
94 ---@-----@--A----@--B--C plus debian/ (but no debian/patches)
95 / / / no ref refers to this: we
96 --#-----#-------#-----> upstream reconstruct its identity by
97 inspecting interchange branch
100 1,2,3 commits touching upstream files only
101 A,B,C commits touching debian/ only
102 B3 mixed commit (eg made by an NMUer)
105 -@- anchor merge, takes contents of debian/ from the
106 / previous `breakwater' commit and rest from upstream
108 -/- pseudomerge; contents are identical to
109 / parent lower on diagram.
111 % dgit-generated commit of debian/patches.
112 `3.0 (quilt)' only; generally dropped by git-debrebase.
114 * Maintainer's HEAD was here while they were editing,
115 before they said they were done, at which point their
116 tools made -/- (and maybe %) to convert to
117 the fast-forwarding interchange branch.
119 ! NMUer's HEAD was here when they said `dgit push'.
120 Rebase branch launderer turns each ! into an
123 =head1 BRANCHES AND BRANCH STATES - OVERVIEW
125 git-debrebase has one primary branch,
126 the B<interchange branch>.
127 This branch is found on Debian contributor's workstations
128 (typically, a maintainer would call it B<master>),
129 in the Debian dgit git server as the suite branch (B<dgit/dgit/sid>)
130 and on other git servers which support Debian work
131 (eg B<master> on salsa).
133 The interchange branch is fast-forwarding
134 (by virtue of pseudomerges, where necessary).
136 It is possible to have multiple different interchange branches
137 for the same package,
138 stored as different local and remote git branches.
139 However, divergence should be avoided where possible -
140 see L</OTHER MERGES>.
142 A suitable interchange branch can be used directly with dgit.
143 In this case each dgit archive suite branch is a separate
146 Within the ancestry of the interchange branch,
147 there is another important, implicit branch, the
149 The breakwater contains unmodified upstream source,
150 but with Debian's packaging superimposed
151 (replacing any C<debian/> directory that may be in upstream).
152 The breakwater does not contain any representation of
153 the delta queue (not even debian/patches).
154 The part of the breakwater processed by git-debrebase
155 is the part since the most reecent B<anchor>,
156 which is usually a special merge generated by git-debrebase.
158 When working, locally,
159 the user's branch can be in a rebasing state,
160 known as B<unstitched>.
161 While a branch is unstitched,
162 it is not in interchange format.
163 The previous interchange branch tip
165 so that the previous history
168 stitched into the fast-forwarding interchange form.
170 An unstitched branch may be in
173 which means it has a more particular special form
174 convenient for manipulating the delta queue.
176 =head1 BRANCH CONTENTS - DETAILED SPECIFICATION
178 It is most convenient to describe the
181 A breakwater is B<fast-forwarding>,
182 but is not usually named by a ref.
183 It contains B<in this order> (ancestors first):
190 which is usually a special two-parent merge:
192 a previous branch tip with Debian packaging tip
193 (perhaps a previous breakwater tip)
194 whose upstream files are irrelevant,
195 and whose packaging files are identical to the anchor's.
196 The second parent is an upstream source commit,
197 whose packaging files (if any) are irrelevant,
198 and whose upstream files are identical to the anchor's.
199 Anchor merges always contain
200 C<[git-debrebase anchor: ...]>
201 as a line in the commit message.
203 an anchor may be a single-parent commit which introduces
204 the C<debian/> directory and makes no other changes:
205 ie, the start of Debian packaging.
209 Zero or more single-parent commits
210 containing only packaging changes.
211 (And no quilt patch changes.)
217 branch state is B<rebasing>.
218 A laundered branch is based on a breakwater
219 but also contains, additionally,
220 B<after> the breakwater,
221 a representation of the delta queue:
225 =item Delta queue commits
227 Zero or more single-parent commits
228 contaioning only changes to upstream files.
234 (ie, unstitched but unlaundered)
235 branch state is also B<rebasing>.
236 It has the same contents as the laundered state,
237 except that it may contain,
239 in B<in any order but after the breakwater>:
243 =item Linear commits to the source
245 Further commit(s) containing changes to
249 possibly mixed within a single commit.
250 (But not quilt patch changes.)
252 =item Quilt patch addition for `3.0 (quilt)'
254 Commit(s) which add patches to B<debian/patches/>,
255 and add those patches to the end of B<series>.
257 These are only necessary when working with
258 packages in C<.dsc 3.0 (quilt)> format.
259 For git-debrebase they are purely an output;
260 they are deleted when branches are laundered.
261 git-debrebase takes care to make a proper patch
262 series out of the delta queue,
263 so that any resulting source packages are nice.
269 branch is B<fast forwarding>.
270 It has the same contents as an
271 unlaundered branch state,
272 but may (and usually will) additionally contain
274 possibly intermixed with the extra commits
275 which may be found on an unstitched unlaundered branch):
279 =item Pseudomerge to make fast forward
281 A pseudomerge making the branch fast forward from
283 The contributing parent is itself in interchange format.
284 Normally the overwritten parent is
285 a previous tip of an interchange branch,
286 but this is not necessary as the overwritten
287 parent is not examined.
289 If the two parents have identical trees,
290 the contributing parent is taken to be
291 the one with the later commit date,
292 or if the commit dates are the same,
295 =item dgit dsc import
297 Debian .dsc source package import(s) made by dgit.
298 Each such import must be a two-parent pseudomerge
299 whose contributing parent is in the special
300 dgit format (not described further here).
301 The overwritten parent must be
302 the previous interchange tip.
303 This is the form normally generated by dgit
304 when it imports .dsc-based uploads.
308 =head1 STITCHING, PSEUDO-MERGES, FFQ RECORD
310 Whenever the branch C<refs/B> is unstitched,
311 the previous head is recorded in the git ref C<refs/ffq-prev/B>.
313 Unstiched branches are not fast forward from the published
314 interchange branches [1].
315 So before a branch can be pushed,
316 the right pseudomerge must be reestablished.
317 This is the stitch operation,
318 which consumes the ffq-prev ref.
320 When the user has an unstitched branch,
321 they may rewrite it freely,
322 from the breakwater tip onwards.
323 Such a git rebase is the default operation for git-debrebase.
324 Rebases should not go back before the breakwater tip,
325 and certainly not before the most recent anchor.
327 Unstitched branches must not be pushed to interchange branch refs
328 (by the use of C<git push -f> or equivalent).
329 It is OK to share an unstitched branch
330 in similar circumstances and with similar warnings
331 to sharing any other rebasing git branch.
333 [1] Strictly, for a package
334 which has never had a Debian delta queue,
335 the interchange and breakwater branches may be identical,
336 in which case the unstitched branch is fast forward
337 from the interchange branch and no pseudomerge is needed.
339 When ffq-prev is not present,
340 C<refs/debrebase-last/B> records some ancestor of refs/B,
341 (usually, the result of last stitch).
342 This can be used to quickly determine whether refs/B
343 is being maintained in git-debrebase form.
347 Note that the representation described here does not permit
348 general merges on any of the relevant branches.
349 For this reason the tools will try to help the user
350 avoid divergence of the interchange branch.
352 See dgit-maint-rebase(7) XXX TBD
353 for a discussio of what kinds of behaviours
356 they might generate such merges.
358 Automatic resolution of divergent interchange branches
359 (or laundering of merges on the interchange branch)
360 is thought to be possible,
361 but there is no tooling for this yet:
363 Nonlinear (merging) history in the interchange branch is awkward
364 because it (obviously) does not preserve
365 the linearity of the delta queue.
366 Easy merging of divergent delta queues is a research problem.
368 Nonlinear (merging) history in the breakwater branch is
369 in principle tolerable,
370 but each of the parents would have to be, in turn,
372 and difficult qeustions arise if they don't have the same anchor.
374 We use the commit message annotation to
375 distinguish the special anchor merges from other general merges,
376 so we can at least detect unsupported merges.
378 =head1 LEGAL OPERATIONS
380 The following basic operations follows from this model
381 (refer to the diagram above):
385 =item Append linear commits
387 No matter the branch state,
388 it is always fine to simply git commit
389 (or cherry-pick etc.)
390 commits containing upstream file changes, packaging changes,
393 (This may make the branch unlaundered.)
397 Record the previous head in ffq-prev,
398 if we were stitched before
399 (and delete debrebase-last).
401 Reorganise the current branch so that the packaging
403 followed by the delta queue,
404 turning C<-@-A-1-2-B3> into C<...@-A-B-1-2-3>.
406 Drop pseudomerges and any quilt patch additions.
408 =item Interactive rebase
410 With a laundered branch,
411 one can do an interactive git rebase of the delta queue.
413 =item New upstream rebase
415 Start rebasing onto a new upstream version,
416 turning C<...#..@-A-B-1-2-3> into C<(...#..@-A-B-, ...#'-)@'-1-2>.
418 This has to be a wrapper around git-rebase,
419 which prepares @' and then tries to rebase 1 2 onto @'.
420 If the user asks for an interactive rebase,
421 @' doesn't appear in the commit list, since
422 @' is the newbase of the rebase (see git-rebase(1)).
424 Note that the construction of @' cannot fail
425 because @' simply copies debian/ from B and and everything else from #'.
426 (Rebasing A and B is undesirable.
427 We want the debian/ files to be non-rebasing
428 so that git log shows the packaging history.)
433 whose contributing parent to is the unstitched branch
435 whose overwritten parent is ffq-prev,
436 consuming ffq-prev in the process
437 (and writing debrebase-last instead).
438 Ideally the contributing parent would be a laundered branch,
439 or perhaps a laundered branch with a quilt patch addition commit.
441 =item Commit quilt patches
443 To generate a tree which can be represented as a
444 3.0 (quilt) .dsc source packages,
445 the delta queue must be reified inside the git tree
446 in B<debian/patches/>.
447 These patch files can be stripped out and/or regenerated as needed.
451 =head1 COMMIT MESSAGE ANNOTATIONS
453 git-debrebase makes annotations
454 in the messages of commits it generates.
458 [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
460 git-debrebase does not pay attention to anything after the colon,
463 The full set of annotations is:
464 [git-debrebase: split mixed commit, debian part]
465 [git-debrebase: split mixed commit, upstream-part]
466 [git-debrebase: convert dgit import, debian changes]
467 [git-debrebase anchor: convert dgit import, upstream changes]
469 [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
470 [git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge]
471 [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
473 [git-debrebase convert-from-gbp: drop patches]
474 [git-debrebase anchor: declare upstream]
475 [git-debrebase pseudomerge: stitch]
477 [git-debrebase convert-to-gbp: commit patches]
479 Only anchor merges have the C<[git-debrebase anchor: ...]> tag.
480 Single-parent anchors are not generated by git-debrebase,
481 and when made manually should not be tagged.
483 The C<split mixed commit> and C<convert dgit import>
484 tags are added to the pre-existing commit message,
485 when git-debrebase rewrites the commit.
487 =head1 APPENDIX - DGIT IMPORT HANDLING
489 Consider a non-dgit NMU followed by a dgit NMU:
491 interchange --/--B3!--%--/----D*-->
504 --#--------> upstream
509 =XBC% dgit tarball import of .debian.tar.gz containing
510 Debian packaging including changes B C and quilt patches
512 0 dgit tarball import of upstream tarball
513 00 dgit tarball import of supplementary upstream tarball
514 &_ dgit nearly-breakwater import
515 &' git-debrebase converted import (upstream files only)
516 D' git-debrebase converted debian/ changes import
518 * ** before and after HEAD
520 We want to transform this into:
524 =item I. No new upstream version
527 --/--B3!--%--/------D*-------------/-->
538 --@--A-----B-----------------------C--D
540 --#----------------------------------------->
542 =item II. New upstream
546 --/--B3!--%--/------D*-------------/-->
557 --@--A-----B--------------------@--C--D
559 --#----------------------- - - / - - ----->
570 dgit-maint-rebase(7),