diff options
| -rw-r--r-- | git-debrebase.1.pod | 22 | ||||
| -rw-r--r-- | git-debrebase.5.pod | 76 |
2 files changed, 61 insertions, 37 deletions
diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod index 9140702..7e12624 100644 --- a/git-debrebase.1.pod +++ b/git-debrebase.1.pod @@ -17,8 +17,11 @@ This is the command line reference. Please read the tutorial L<dgit-maint-debrebase(5)>. For background, theory of operation, -and definitions of the terms used here, -see L<git-debrebase(5)>. +and definitions see L<git-debrebase(5)>. + +You should read this manpage in conjunction with +L<git-debrebase(5)/TERMINOLOGY>, +which defines many important terms used here. =head1 PRINCIPAL OPERATIONS @@ -299,14 +302,15 @@ in the text for the relvant operation. =item --anchor=<commit-ish> -Treats <commit-ish> as an anchor, -regardless of what it's actually like. +Treats <commit-ish> as an anchor. +This overrides the usual automatic commit classification logic. -(It is a problem for -git-debrebase new-upstream operations -if <commit-ish> is the previous anchor to be used, -because treating an arbitrary commit as an anchor -means forgoing upstream coherency checks.) +It also disables some coherency checks +which depend on metadata extracted from its commit message, +so +it is a problem if <commit-ish> is the anchor +for the previous upstream version in +git-debrebase new-upstream operations. =item -D diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod index f749f62..d3ecda8 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,7 +76,8 @@ a series of git commits. Files in B<debian/patches/> 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. =back @@ -148,7 +151,8 @@ there is another important, implicit branch, the B<breakwater>. The breakwater contains unmodified upstream source, but with Debian's packaging superimposed -(replacing any C<debian/> directory that may be in upstream). +(replacing any C<debian/> 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 +192,24 @@ It contains B<in this order> (ancestors first): An B<anchor> 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<debian/> directory and makes no other changes: @@ -287,21 +298,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 +477,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] |