X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=git-debrebase.5.pod;h=6d61baad9fd0ebb471157314b957d01dc3de9b97;hp=ce982369c3132af1110e2d6d4f62b104659403c0;hb=b822b6c13035de35290d03c497fdbd72560e3d34;hpb=d76a377b48bbcc3dcaf85100588a2d5d4d151db4 diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod index ce982369..6d61baad 100644 --- a/git-debrebase.5.pod +++ b/git-debrebase.5.pod @@ -10,14 +10,14 @@ Debian packages based on upstream source code. The Debian packaging has a fast forwarding history. -The changes to upstream files are represented +The delta queue (changes to upstream files) is represented as a series of individual git commits, which can worked on with rebase, and also shared. git-debrebase is designed to work well with dgit. git-debrebase can also be used in workflows without source packages, -for example to work on Debian-format packages outside Debian. +for example to work on Debian-format packages outside or alongside Debian. git-debrebase is not very suitable for use by Debian derivatives, to work on packages inherited from Debian, @@ -28,7 +28,7 @@ provided by your upstream. ------/--A!----/--B3!--%--/--> interchange view / / / with debian/ directory - % % % all upstream changes applied + % % % entire delta queue applied / / / 3.0 (quilt) has debian/patches / / 3* / / / @@ -54,11 +54,11 @@ provided by your upstream. / parent lower on diagram. % dgit-generated commit of debian/patches. - `3.0 (quilt)' only; dropped by rebase tool. + `3.0 (quilt)' only; generally dropped by git-debrebase. * Maintainer's HEAD was here while they were editing, before they said they were done, at which point their - tools generated [% and] -/- commit[s] to convert to + tools made -/- (and maybe %) to convert to the fast-forwarding interchange branch. ! NMUer's HEAD was here when they said `dgit push'. @@ -72,7 +72,7 @@ the B. This branch is found on Debian contributor's workstations (typically, a maintainer would call it B), in the Debian dgit git server as the suite branch (B) -and on other git servers which support Debian owrk +and on other git servers which support Debian work (eg B on salsa). The interchange branch is fast-forwarding @@ -82,35 +82,39 @@ It is possible to have multiple different interchange branches for the same package, stored as different local and remote git branches. However, divergence should be avoided where possible - -see L. +see L. A suitable interchange branch can be used directly with dgit. In this case each dgit archive suite branch is a separate interchange branch. -Within the ancenstry of the interchange branch, -there is another importnt, implicit branch, the +Within the ancestry of the interchange branch, +there is another important, implicit branch, the B. The breakwater contains unmodified upstream source, but with Debian's packaging superimposed (replacing any C directory that may be in upstream). -The breakwater does not contain any representation -of Debian's changes to upstream files. -The breakwater starts at an B, +The breakwater does not contain any representation of +the delta queue. +The part of the breakwater processed by git-debrebase +is the part since the most reecent B, which is usually a special merge generated by git-debrebase. When working, locally, the user's branch can be in a rebasing state, known as B. -When a branch is unstitched, -its previous tip is recorded so that it can later be +While a branch is unstitched, +its previous tip is recorded, +so that the previous history +and the user's work +can later be stitched into the fast-forwarding interchange form. An unstitched branch may be in B state, which means it has a more particular special form -convenient for manipulating the changes to upstream files. +convenient for manipulating the delta queue. =head1 BRANCH CONTENTS @@ -125,10 +129,12 @@ It contains B (ancestors first): An B commit, which is usually a special two-parent merge: -The first parent is a previous breakwater branch, +The first parent is +a previous branch tip with Debian packaging tip +(perhaps a previous breakwater tip) whose upstream files are irrelevant, and whose packaging files are identical to the anchor's. -The second parent is an upstream source commit; +The second parent is an upstream source commit, whose packaging files (if any) are irrelevant, and whose upstream files are identical to the anchor's. Anchor merges always contain @@ -143,9 +149,9 @@ ie, the start of Debian packaging. Zero or more single-parent commits containing only packaging changes. -(And no changes to B.) +(And no quilt patch changes.) -=item Delta from upstream +=item Delta queue commits Zero or more single-parent commits contaioning only changes to upstream files. @@ -169,14 +175,16 @@ to upstream files and/or to packaging, possibly mixed within a single commit. -(But no changes to B.) +(But not quilt patch changes.) -=item Patch addition for `3.0 (quilt)' +=item Quilt patch addition for `3.0 (quilt)' Commit(s) which add patches to B, and add those patches to the end of B. -These are only necessary or useful when working with +These are only necessary when working with packages in C<.dsc 3.0 (quilt)> format. +For git-debrebase they are purely an output; +they are deleted when branches are laundered. =back @@ -199,6 +207,12 @@ a previous tip of the interchange branch, but this is not necessary as the overwritten parent is not examined. +If the two parents have identical trees, +the contributing parent is taken to be +the one with the later commit date, +or if the commit dates are the same, +the left parent. + =item dgit dsc import Debian .dsc source package import(s) made by dgit. @@ -206,8 +220,9 @@ Each such import must be a two-parent pseudomerge whose contributing parent is in the special dgit format (not described further here). The overwritten parent must be -the previous interchange tip -(and will be generated that way by normal use of dgit). +the previous interchange tip. +This is the form normally generated by dgit +when it imports .dsc-based uploads. =back @@ -237,7 +252,7 @@ in similar circumstances and with similar warnings to sharing any other rebasing git branch. [1] Strictly, for a package -which has never had Debian changes to upstream files, +which has never had a Debian delta queue, the interchange and breakwater branches may be identical, in which case the unstitched branch is fast forward from the interchange branch and no pseudomerge is needed. @@ -289,8 +304,9 @@ or both. Record the previous tip in ffq-prev, if we were stitched before. -Reorganise the current branch so that the debian/ +Reorganise the current branch so that the packaging changes come first, +followed by the delta queue, turning C<-@-A-1-2-B3> into C<...@-A-B-1-2-3>. Drop pseudomerges and any quilt patches. @@ -308,7 +324,7 @@ turning C<...#..@-A-B-1-2-3> into C<(...#..@-A-B-|...#'-)@'-1-2>. This has to be a wrapper around git-rebase, which prepares @' and then tries to rebase 1 2 onto @'. If the user asks for an interactive rebase, -@' doesn't appear in thec ommit list. +@' doesn't appear in the commit list. Note that the construction of @' cannot fail because @' simply copies debian/ from B and and everything else from #'. @@ -319,9 +335,14 @@ so that git log shows the packaging history.) =item Stitch Make a pseudomerge, -overwriting (and consuming) ffq-prev. +whose contributing parent to is the unstitched branch +and +whose overwritten parent is ffq-prev, +consuming ffq-prev in the process. +Ideally the contributing parent would be a laundered branch, +or perhaps a laundered branch with a quilt patch addition commit. -=item Commit patches +=item Commit quilt patches To generate a tree which can be represented as a 3.0 (quilt) .dsc source packages, @@ -331,6 +352,42 @@ in B. =back +=head1 COMMIT MESSAGE ANNOTATIONS + +git-debrebase makes annotations +in the messages of commits it generates. + +The general form is + + [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE] + +git-debrebase does not pay attention to anything after the colon, +so PROSE is ignored. + +The full set of annotations is: + [git-debrebase: split mixed commit, debian part] + [git-debrebase: split mixed commit, upstream-part] + [git-debrebase: convert dgit import, debian changes] + [git-debrebase anchor: convert dgit import, upstream changes] + + [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream] + [git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge] + [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog] + + [git-debrebase convert-from-gbp: drop patches] + [git-debrebase anchor: declare upstream] + [git-debrebase pseudomerge: stitch] + + [git-debrebase convert-to-gbp: commit patches] + +Only anchor merges have the C<[git-debrebase anchor: ...]> tag. +Single-parent anchors are not generated by git-debrebase, +and when made manually should not be tagged. + +The C and C +tags are added to the pre-existing commit message, +when git-debrebase rewrites the commit. + =head1 TERMINOLOGY =over @@ -338,7 +395,7 @@ in B. =item Pseudomerge A merge which does not actually merge the trees; -instead, it takes its tree by construction from one parent. +instead, it takes its tree, by construction, from only one parent. These are used to make a rewritten history fast forward from a previous tip, so that it can be pushed and pulled normally. @@ -363,6 +420,17 @@ Files in the source tree outside B. These may include unmodified source from upstream, but also files which have been modified or created for Debian. +=item Delta queue + +Debian's changes to upstream files: +a series of git commits. + +=item Quilt patches + +Files in B generated for the benefit of +dpkg-source's 3.0 (quilt) .dsc source package format. +Not used, and often deleted, by git-debrebase. + =back =head1 APPENDIX - DGIT IMPORT HANDLING @@ -388,7 +456,7 @@ Consider a non-dgit NMU followed by a dgit NMU: Key: =XBC% dgit tarball import of .debian.tar.gz containing - Debian packaging including changes B C and patches + Debian packaging including changes B C and quilt patches 0 dgit tarball import of upstream tarball 00 dgit tarball import of supplementary upstream tarball