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