chiark / gitweb /
exit status: Fix dgit-badcommit-fixup to use Debian::Dgit::ExitStatus
[dgit.git] / git-debrebase.5.pod
1 =head1 NAME
2
3 git-debrebase - git data model for Debian packaging
4
5 =head1 INTRODUCTION
6
7 git-debrebase is a tool for representing in git,
8 and manpulating,
9 Debian packages based on upstream source code.
10
11 The Debian packaging
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,
16 and also shared.
17
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.
21
22 git-debrebase
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.
29
30 =head1 TERMINOLOGY
31
32 =over
33
34 =item Pseudomerge
35
36 A merge which does not actually merge the trees;
37 instead, it is constructed by taking the tree
38 from one of the parents
39 (ignoring the contents of the other parents).
40 These are used to make a rewritten history fast forward
41 from a previous tip,
42 so that it can be pushed and pulled normally.
43 Manual construction of pseudomerges can be done with
44 C<git merge -s ours>
45 but is not normally needed when using git-debrebase.
46
47 =item Packaging files
48
49 Files in the source tree within B<debian/>,
50 excluding anything in B<debian/patches/>.
51
52 =item Upstream
53
54 The version of the package without Debian's packaging.
55 Typically provided by the actual upstream project,
56 and sometimes tracked by Debian contributors in a branch C<upstream>.
57
58 Upstream contains upstream files,
59 but some upstreams also contain packaging files in B<debian/>.
60 Any such non-upstream files found in upstream
61 are thrown away by git-debrebase
62 each time a new upstream version is incorporated.
63
64 =item Upstream files
65
66 Files in the source tree outside B<debian/>.
67 These may include unmodified source from upstream,
68 but also files which have been modified or created for Debian.
69
70 =item Delta queue
71
72 Debian's changes to upstream files:
73 a series of git commits.
74
75 =item Quilt patches
76
77 Files in B<debian/patches/> generated for the benefit of
78 dpkg-source's 3.0 (quilt) .dsc source package format.
79 Not used, often deleted, and regenerated when needed
80 (such as when uploading to Debian),
81 by git-debrebase.
82
83 =item Interchange branch; breakwater; stitched; laundered
84
85 See L</BRANCHES AND BRANCH STATES - OVERVIEW>.
86
87 =item Anchor; Packaging
88
89 See L</BRANCH CONTENTS - DETAILED SPECIFICATION>.
90
91 =item ffq-prev; debrebase-last
92
93 See L</STITCHING, PSEUDO-MERGES, FFQ RECORD>.
94
95 =back
96
97 =head1 DIAGRAM
98
99            ------/--A!----/--B3!--%--/--> interchange view
100                 /        /          /      with debian/ directory
101                %        %          %       entire delta queue applied
102               /        /          /        3.0 (quilt) has debian/patches
103              /        /          3*       "master" on Debian git servers
104             /        /          /
105            2*       2*         2
106           /        /          /
107          1        1          1    breakwater branch, merging baseline
108         /        /          /     unmodified upstream code
109     ---@-----@--A----@--B--C      plus debian/ (but no debian/patches)
110       /     /       /                     no ref refers to this: we
111    --#-----#-------#-----> upstream        reconstruct its identity by
112                                            inspecting interchange branch
113     Key:
114
115       1,2,3   commits touching upstream files only
116       A,B,C   commits touching debian/ only
117       B3      mixed commit (eg made by an NMUer)
118       #       upstream releases
119
120      -@-      anchor merge, takes contents of debian/ from the
121      /         previous `breakwater' commit and rest from upstream
122
123      -/-      pseudomerge; contents are identical to
124      /         parent lower on diagram.
125
126       %       dgit- or git-debrebase- generated commit of debian/patches.
127               `3.0 (quilt)' only; generally dropped by git-debrebase.
128
129       *       Maintainer's HEAD was here while they were editing,
130               before they said they were done, at which point their
131               tools made -/- (and maybe %) to convert to
132               the fast-forwarding interchange branch.
133
134       !       NMUer's HEAD was here when they said `dgit push'.
135               Rebase branch launderer turns each ! into an
136               equivalent *.
137
138 =head1 BRANCHES AND BRANCH STATES - OVERVIEW
139
140 git-debrebase has one primary branch,
141 the B<interchange branch>.
142 This branch is found on Debian contributor's workstations
143 (typically, a maintainer would call it B<master>),
144 in the Debian dgit git server as the suite branch (B<dgit/dgit/sid>)
145 and on other git servers which support Debian work
146 (eg B<master> on salsa).
147
148 The interchange branch is fast-forwarding
149 (by virtue of pseudomerges, where necessary).
150
151 It is possible to have multiple different interchange branches
152 for the same package,
153 stored as different local and remote git branches.
154 However, divergence should be avoided where possible -
155 see L</OTHER MERGES>.
156
157 A suitable interchange branch can be used directly with dgit.
158 In this case each dgit archive suite branch is a separate
159 interchange branch.
160
161 Within the ancestry of the interchange branch,
162 there is another important, implicit branch, the
163 B<breakwater>.
164 The breakwater contains unmodified upstream source,
165 but with Debian's packaging superimposed
166 (replacing any C<debian/> directory that may be in
167 the upstream commits).
168 The breakwater does not contain any representation of
169 the delta queue (not even debian/patches).
170 The part of the breakwater processed by git-debrebase
171 is the part since the most reecent B<anchor>,
172 which is usually a special merge generated by git-debrebase.
173
174 When working, locally,
175 the user's branch can be in a rebasing state,
176 known as B<unstitched>.
177 While a branch is unstitched,
178 it is not in interchange format.
179 The previous interchange branch tip
180 tip is recorded,
181 so that the previous history
182 and the user's work
183 can later be
184 stitched into the fast-forwarding interchange form.
185
186 An unstitched branch may be in
187 B<laundered>
188 state,
189 which means it has a more particular special form
190 convenient for manipulating the delta queue.
191
192 =head1 BRANCH CONTENTS - DETAILED SPECIFICATION
193
194 It is most convenient to describe the
195 B<breakwater>
196 branch first.
197 A breakwater is B<fast-forwarding>,
198 but is not usually named by a ref.
199 It contains B<in this order> (ancestors first):
200
201 =over
202
203 =item Anchor
204
205 An B<anchor> commit,
206 which is usually a special two-parent merge:
207
208 The first parent
209 contains the most recent version, at that point,
210 of the Debian packaging (in debian/);
211 it also often contains upstream files,
212 but they are to be ignored.
213 Often the first parent is a previous breakwater tip.
214
215 The second parent
216 is an upstream source commit.
217 It may sometimes contain a debian/ subdirectory,
218 but if so that is to be ignored.
219 The second parent's upstream files
220 are identical to the anchor's.
221 Anchor merges always contain
222 C<[git-debrebase anchor: ...]>
223 as a line in the commit message.
224
225 Alternatively,
226 an anchor may be a single-parent commit which introduces
227 the C<debian/> directory and makes no other changes:
228 ie, the start of Debian packaging.
229
230 =item Packaging
231
232 Zero or more single-parent commits
233 containing only packaging changes.
234 (And no quilt patch changes.)
235
236 =back
237
238 The
239 B<laundered>
240 branch state is B<rebasing>.
241 A laundered branch is based on a breakwater
242 but also contains, additionally,
243 B<after> the breakwater,
244 a representation of the delta queue:
245
246 =over
247
248 =item Delta queue commits
249
250 Zero or more single-parent commits
251 contaioning only changes to upstream files.
252
253 =back
254
255 The merely
256 B<unstitched>
257 (ie, unstitched but unlaundered)
258 branch state is also B<rebasing>.
259 It has the same contents as the laundered state,
260 except that it may contain,
261 additionally,
262 in B<in any order but after the breakwater>:
263
264 =over
265
266 =item Linear commits to the source
267
268 Further commit(s) containing changes to
269 to upstream files
270 and/or
271 to packaging,
272 possibly mixed within a single commit.
273 (But not quilt patch changes.)
274
275 =item Quilt patch addition for `3.0 (quilt)'
276
277 Commit(s) which add patches to B<debian/patches/>,
278 and add those patches to the end of B<series>.
279
280 These are only necessary when working with
281 packages in C<.dsc 3.0 (quilt)> format.
282 For git-debrebase they are purely an output;
283 they are deleted when branches are laundered.
284 git-debrebase takes care to make a proper patch
285 series out of the delta queue,
286 so that any resulting source packages are nice.
287
288 =back
289
290 Finally, an
291 B<interchange>
292 branch is B<fast forwarding>.
293 It has the same contents as an
294 unlaundered branch state,
295 but may (and usually will) additionally contain
296 (in some order,
297 possibly intermixed with the extra commits
298 which may be found on an unstitched unlaundered branch):
299
300 =over
301
302 =item Pseudomerge to make fast forward
303
304 A pseudomerge making the branch fast forward from
305 previous history.
306 The contributing parent is itself in interchange format.
307 Normally the overwritten parent is
308 a previous tip of an interchange branch,
309 but this is not necessary as the overwritten
310 parent is not examined.
311
312 If the two parents have identical trees,
313 the one with the later commit date
314 (or, if the commit dates are the same,
315 the first parent)
316 is treated as
317 the contributing parent.
318
319 =item dgit dsc import pseudomerge
320
321 Debian .dsc source package import(s)
322 made by dgit
323 (during dgit fetch of a package most recently 
324 uploaded to Debian without dgit,
325 or during dgit import-dsc).
326
327 git-debrebase requires that
328 each such import is in the fast-forwarding
329 format produced by dgit:
330 a two-parent pseudomerge,
331 whose contributing parent is in the
332 non-fast-forwarding
333 dgit dsc import format (not described further here),
334 and whose overwritten parent is
335 the previous interchange tip
336 (eg, the previous tip of the dgit suite branch).
337
338 =back
339
340 =head1 STITCHING, PSEUDO-MERGES, FFQ RECORD
341
342 Whenever the branch C<refs/B> is unstitched,
343 the previous head is recorded in the git ref C<refs/ffq-prev/B>.
344
345 Unstiched branches are not fast forward from the published
346 interchange branches [1].
347 So before a branch can be pushed,
348 the right pseudomerge must be reestablished.
349 This is the stitch operation,
350 which consumes the ffq-prev ref.
351
352 When the user has an unstitched branch,
353 they may rewrite it freely,
354 from the breakwater tip onwards.
355 Such a git rebase is the default operation for git-debrebase.
356 Rebases should not go back before the breakwater tip,
357 and certainly not before the most recent anchor.
358
359 Unstitched branches must not be pushed to interchange branch refs
360 (by the use of C<git push -f> or equivalent).
361 It is OK to share an unstitched branch
362 in similar circumstances and with similar warnings
363 to sharing any other rebasing git branch.
364
365 [1] Strictly, for a package
366 which has never had a Debian delta queue,
367 the interchange and breakwater branches may be identical,
368 in which case the unstitched branch is fast forward
369 from the interchange branch and no pseudomerge is needed.
370
371 When ffq-prev is not present,
372 C<refs/debrebase-last/B> records some ancestor of refs/B,
373 (usually, the result of last stitch).
374 This can be used to quickly determine whether refs/B
375 is being maintained in git-debrebase form.
376
377 =head1 OTHER MERGES
378
379 Note that the representation described here does not permit
380 general merges on any of the relevant branches.
381 For this reason the tools will try to help the user
382 avoid divergence of the interchange branch.
383
384 See dgit-maint-rebase(7) XXX TBD
385 for a discussio of what kinds of behaviours
386 should be be avoided
387 because
388 they might generate such merges.
389
390 Automatic resolution of divergent interchange branches
391 (or laundering of merges on the interchange branch)
392 is thought to be possible,
393 but there is no tooling for this yet:
394
395 Nonlinear (merging) history in the interchange branch is awkward
396 because it (obviously) does not preserve
397 the linearity of the delta queue.
398 Easy merging of divergent delta queues is a research problem.
399
400 Nonlinear (merging) history in the breakwater branch is
401 in principle tolerable,
402 but each of the parents would have to be, in turn,
403 a breakwater,
404 and difficult qeustions arise if they don't have the same anchor.
405
406 We use the commit message annotation to
407 distinguish the special anchor merges from other general merges,
408 so we can at least detect unsupported merges.
409
410 =head1 LEGAL OPERATIONS
411
412 The following basic operations follows from this model
413 (refer to the diagram above):
414
415 =over
416
417 =item Append linear commits
418
419 No matter the branch state,
420 it is always fine to simply git commit
421 (or cherry-pick etc.)
422 commits containing upstream file changes, packaging changes,
423 or both.
424
425 (This may make the branch unlaundered.)
426
427 =item Launder branch
428
429 Record the previous head in ffq-prev,
430 if we were stitched before
431 (and delete debrebase-last).
432
433 Reorganise the current branch so that the packaging
434 changes come first,
435 followed by the delta queue,
436 turning C<-@-A-1-2-B3> into C<...@-A-B-1-2-3>.
437
438 Drop pseudomerges and any quilt patch additions.
439
440 =item Interactive rebase
441
442 With a laundered branch,
443 one can do an interactive git rebase of the delta queue.
444
445 =item New upstream rebase
446
447 Start rebasing onto a new upstream version,
448 turning C<...#..@-A-B-1-2-3> into C<(...#..@-A-B-, ...#'-)@'-1-2>.
449
450 This has to be a wrapper around git-rebase,
451 which prepares @' and then tries to rebase 1 2 onto @'.
452 If the user asks for an interactive rebase,
453 @' doesn't appear in the commit list, since
454 @' is the newbase of the rebase (see git-rebase(1)).
455
456 Note that the construction of @' cannot fail
457 because @' simply copies debian/ from B and and everything else from #'.
458 (Rebasing A and B is undesirable.
459 We want the debian/ files to be non-rebasing
460 so that git log shows the packaging history.)
461
462 =item Stitch 
463
464 Make a pseudomerge,
465 whose contributing parent to is the unstitched branch
466 and
467 whose overwritten parent is ffq-prev,
468 consuming ffq-prev in the process
469 (and writing debrebase-last instead).
470 Ideally the contributing parent would be a laundered branch,
471 or perhaps a laundered branch with a quilt patch addition commit.
472
473 =item Commit quilt patches
474
475 To generate a tree which can be represented as a
476 3.0 (quilt) .dsc source packages,
477 the delta queue must be reified inside the git tree
478 in B<debian/patches/>.
479 These patch files can be stripped out and/or regenerated as needed.
480
481 =back
482
483 =head1 COMMIT MESSAGE ANNOTATIONS
484
485 git-debrebase makes annotations
486 in the messages of commits it generates.
487
488 The general form is
489
490   [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
491
492 git-debrebase treats anything after the colon as a comment,
493 paying no attention to PROSE.
494
495 The full set of annotations is:
496   [git-debrebase: split mixed commit, debian part]
497   [git-debrebase: split mixed commit, upstream-part]
498   [git-debrebase: convert dgit import, debian changes]
499   [git-debrebase anchor: convert dgit import, upstream changes]
500
501   [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
502   [git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge]
503   [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
504   [git-debrebase: export and commit patches]
505
506   [git-debrebase convert-from-gbp: drop patches]
507   [git-debrebase anchor: declare upstream]
508   [git-debrebase pseudomerge: stitch]
509
510   [git-debrebase convert-to-gbp: commit patches]
511
512 Only anchor merges have the C<[git-debrebase anchor: ...]> tag.
513 Single-parent anchors are not generated by git-debrebase,
514 and when made manually should not be tagged.
515
516 The C<split mixed commit> and C<convert dgit import>
517 tags are added to the pre-existing commit message,
518 when git-debrebase rewrites the commit.
519
520 =head1 APPENDIX - DGIT IMPORT HANDLING
521
522 The dgit .dsc import format is not documented or specified
523 (so some of the following terms are not defined anywhere).
524 The dgit import format it is defined by the implementation in dgit,
525 of which git-debrebase has special knowledge.
526
527 Consider a non-dgit NMU followed by a dgit NMU:
528
529             interchange --/--B3!--%--//----D*-->
530                          /          /
531                         %          4
532                        /          3
533                       /          2
534                      /          1
535                     2          &_
536                    /          /| \
537                   1          0 00 =XBC%
538                  /
539                 /
540           --@--A     breakwater
541            /
542         --#--------> upstream
543
544
545  Supplementary key:
546
547     =XBC%     dgit tarball import of .debian.tar.gz containing
548                Debian packaging including changes B C and quilt patches
549     0         dgit tarball import of upstream tarball
550     00        dgit tarball import of supplementary upstream piece
551     &_        dgit import nearly-breakwater-anchor
552     //        dgit fetch / import-dsc pseudomerge to make fast forward
553
554     &'        git-debrebase converted import (upstream files only)
555     C'        git-debrebase converted packaging change import
556
557     * **      before and after HEAD
558
559 We want to transform this into:
560
561 =over
562
563 =item I. No new upstream version
564
565  (0 + 00 eq #)
566                         --/--B3!--%--//-----D*-------------/-->
567                          /          /                     /
568                         %          4                     4**
569                        /          3                     3
570                       /          2                     2
571                      /          1                     1
572                     2          &_                    /
573                    /          /| \                  /
574                   1          0 00 =XBC%            /
575                  /                                /
576                 /                                /
577           --@--A-----B---------------------C'---D
578            /
579         --#----------------------------------------->
580
581 =item II. New upstream
582
583  (0 + 00 neq #)
584
585                         --/--B3!--%--//-----D*-------------/-->
586                          /          /                     /
587                         %          4                     4**
588                        /          3                     3
589                       /          2                     2
590                      /          1                     1
591                     2          &_                    /
592                    /          /| \                  /
593                   1          0 00 =XBC%            /
594                  /                                /
595                 /                                /
596           --@--A-----B-----------------@---C'---D
597            /                          /
598         --#--------------------- - - / - - --------->
599                                     /
600                                    &'
601                                   /|
602                                  0 00
603
604 =back
605
606 =head1 SEE ALSO
607
608 git-debrebase(1),
609 dgit-maint-rebase(7),
610 dgit(1)