X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=git-debrebase.5.pod;h=5cfa3761080eb5c6accffa98cfd6682b72cbffa0;hp=b9abba0cb95996556d9e1e9ea386ddcb3fdb4488;hb=6b3cdcf0d595efd96bc8c4220df87f7fd5aaef76;hpb=1c282fc517987649f824fb8241e805c3d3fe68c4 diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod index b9abba0c..5cfa3761 100644 --- a/git-debrebase.5.pod +++ b/git-debrebase.5.pod @@ -27,6 +27,73 @@ provided by your upstream. However, of git-debrebase in Debian does not make anything harder for derivatives, and it can make some things easier. +=head1 TERMINOLOGY + +=over + +=item Pseudomerge + +A merge which does not actually merge the trees; +instead, it is constructed by taking the tree +from one of the parents +(ignoring the contents of the other parents). +These are used to make a rewritten history fast forward +from a previous tip, +so that it can be pushed and pulled normally. +Manual construction of pseudomerges can be done with +C +but is not normally needed when using git-debrebase. + +=item Packaging files + +Files in the source tree within B, +excluding anything in B. + +=item Upstream + +The version of the package without Debian's packaging. +Typically provided by the actual upstream project, +and sometimes tracked by Debian contributors in a branch C. + +Upstream contains upstream files, +but some upstreams also contain packaging files in B. +Any such non-upstream files found in upstream +are thrown away by git-debrebase +each time a new upstream version is incorporated. + +=item Upstream files + +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, often deleted, and regenerated when needed +(such as when uploading to Debian), +by git-debrebase. + +=item Interchange branch; breakwater; stitched; laundered + +See L. + +=item Anchor; Packaging + +See L. + +=item ffq-prev; debrebase-last + +See L. + +=back + =head1 DIAGRAM ------/--A!----/--B3!--%--/--> interchange view @@ -40,9 +107,9 @@ derivatives, and it can make some things easier. 1 1 1 breakwater branch, merging baseline / / / unmodified upstream code ---@-----@--A----@--B--C plus debian/ (but no debian/patches) - / / / no ref refers to this: we + / / / no ref refers to this: we --#-----#-------#-----> upstream reconstruct its identity by - inspecting interchange branch + inspecting interchange branch Key: 1,2,3 commits touching upstream files only @@ -56,7 +123,7 @@ derivatives, and it can make some things easier. -/- pseudomerge; contents are identical to / parent lower on diagram. - % dgit-generated commit of debian/patches. + % dgit- or git-debrebase- generated commit of debian/patches. `3.0 (quilt)' only; generally dropped by git-debrebase. * Maintainer's HEAD was here while they were editing, @@ -96,7 +163,8 @@ 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). +(replacing any C directory that may be in +the upstream commits). The breakwater does not contain any representation of the delta queue (not even debian/patches). The part of the breakwater processed by git-debrebase @@ -136,17 +204,24 @@ It contains B (ancestors first): An B commit, which is usually a special two-parent merge: -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, -whose packaging files (if any) are irrelevant, -and whose upstream files are identical to the anchor's. + +The first parent +contains the most recent version, at that point, +of the Debian packaging (in debian/); +it also often contains upstream files, +but they are to be ignored. +Often the first parent is a previous breakwater tip. + +The second parent +is an upstream source commit. +It may sometimes contain a debian/ subdirectory, +but if so that is to be ignored. +The second parent's upstream files +are identical to the anchor's. Anchor merges always contain C<[git-debrebase anchor: ...]> as a line in the commit message. + Alternatively, an anchor may be a single-parent commit which introduces the C directory and makes no other changes: @@ -235,21 +310,30 @@ 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 first parent. - -=item dgit dsc import - -Debian .dsc source package import(s) made by dgit. -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. -This is the form normally generated by dgit -when it imports .dsc-based uploads. +the one with the later commit date +(or, if the commit dates are the same, +the first parent) +is treated as +the contributing parent. + +=item dgit dsc import pseudomerge + +Debian .dsc source package import(s) +made by dgit +(during dgit fetch of a package most recently +uploaded to Debian without dgit, +or during dgit import-dsc). + +git-debrebase requires that +each such import is in the fast-forwarding +format produced by dgit: +a two-parent pseudomerge, +whose contributing parent is in the +non-fast-forwarding +dgit dsc import format (not described further here), +and whose overwritten parent is +the previous interchange tip +(eg, the previous tip of the dgit suite branch). =back @@ -405,8 +489,8 @@ 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. +git-debrebase treats anything after the colon as a comment, +paying no attention to PROSE. The full set of annotations is: [git-debrebase: split mixed commit, debian part] @@ -417,6 +501,7 @@ The full set of annotations is: [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: export and commit patches] [git-debrebase convert-from-gbp: drop patches] [git-debrebase anchor: declare upstream] @@ -432,63 +517,16 @@ The C and C tags are added to the pre-existing commit message, when git-debrebase rewrites the commit. -=head1 TERMINOLOGY - -=over - -=item Pseudomerge - -A merge which does not actually merge the trees; -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. -Manual construction of pseudomerges can be done with -C -but is not normally needed when using git-debrebase. - -=item Packaging files - -Files in the source tree within B, -excluding anything in B. - -=item Upstream - -The version of the package without Debian's packaging. -Typically provided by the actual upstream project, -and sometimes tracked by Debian contributors in a branch C. - -Upstream contains upstream files, -but some upstreams also contain packaging files in B. -Any such non-upstream files found in upstream -are thrown away by git-debrebase -each time a new upstream version is incorporated. - -=item Upstream files - -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, often deleted, and regenerated when needed, -by git-debrebase. - -=back - =head1 APPENDIX - DGIT IMPORT HANDLING +The dgit .dsc import format is not documented or specified +(so some of the following terms are not defined anywhere). +The dgit import format it is defined by the implementation in dgit, +of which git-debrebase has special knowledge. + Consider a non-dgit NMU followed by a dgit NMU: - interchange --/--B3!--%--/----D*--> + interchange --/--B3!--%--//----D*--> / / % 4 / 3 @@ -499,21 +537,22 @@ Consider a non-dgit NMU followed by a dgit NMU: 1 0 00 =XBC% / / - --@--A breakwater - / - --#--------> upstream + --@--A breakwater + / + --#--------> upstream Supplementary key: =XBC% dgit tarball import of .debian.tar.gz containing - Debian packaging including changes B C and quilt 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 - &_ dgit nearly-breakwater import + 00 dgit tarball import of supplementary upstream piece + &_ dgit import nearly-breakwater-anchor + // dgit fetch / import-dsc pseudomerge to make fast forward + &' git-debrebase converted import (upstream files only) - D' git-debrebase converted debian/ changes import + C' git-debrebase converted packaging change import * ** before and after HEAD @@ -524,43 +563,43 @@ We want to transform this into: =item I. No new upstream version (0 + 00 eq #) - --/--B3!--%--/------D*-------------/--> - / / / - % 4 4** - / 3 3 - / 2 2 - / 1 1 - 2 &_ / - / /| \ / + --/--B3!--%--//-----D*-------------/--> + / / / + % 4 4** + / 3 3 + / 2 2 + / 1 1 + 2 &_ / + / /| \ / 1 0 00 =XBC% / - / / - / / - --@--A-----B-----------------------C--D - / - --#-----------------------------------------> + / / + / / + --@--A-----B---------------------C'---D + / + --#-----------------------------------------> =item II. New upstream (0 + 00 neq #) - --/--B3!--%--/------D*-------------/--> - / / / - % 4 4** - / 3 3 - / 2 2 - / 1 1 - 2 &_ / - / /| \ / + --/--B3!--%--//-----D*-------------/--> + / / / + % 4 4** + / 3 3 + / 2 2 + / 1 1 + 2 &_ / + / /| \ / 1 0 00 =XBC% / - / / - / / - --@--A-----B--------------------@--C--D - / / - --#----------------------- - - / - - -----> - / - &' - /| - 0 00 + / / + / / + --@--A-----B-----------------@---C'---D + / / + --#--------------------- - - / - - ---------> + / + &' + /| + 0 00 =back