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=f749f628b6e0eeb2dfd6ca6ea9bd464b4e1a45fd;hb=15406403f564b23f44124fd6cad61cf143ce2f84;hpb=190c045107f1681dd7f5232bd3ad41088e0a8244 diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod index f749f628..5cfa3761 100644 --- a/git-debrebase.5.pod +++ b/git-debrebase.5.pod @@ -34,7 +34,9 @@ derivatives, and it can make some things easier. =item Pseudomerge A merge which does not actually merge the trees; -instead, it takes its tree, by construction, from only one parent. +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. @@ -74,9 +76,22 @@ a series of git commits. 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, +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 @@ -92,9 +107,9 @@ by git-debrebase. 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 @@ -108,7 +123,7 @@ by git-debrebase. -/- 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, @@ -148,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 @@ -188,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: @@ -287,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 @@ -457,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] @@ -469,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] @@ -486,9 +519,14 @@ when git-debrebase rewrites the commit. =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