X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=git-debrebase.1.pod;h=a91ad3a74e88b9d405694d24064d37a9e1c23ace;hb=9bab0fa49d1ed2d47a3a02ab9c4db1d721b8752e;hp=ba603ba577091b6a5ac84b1637fd2c0a8fd9fb3c;hpb=b5cd66f2a318d196e4497bd428567826f5c2b5d6;p=dgit.git diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod index ba603ba5..a91ad3a7 100644 --- a/git-debrebase.1.pod +++ b/git-debrebase.1.pod @@ -17,12 +17,11 @@ This is the command line reference. Please read the tutorial L. For background, theory of operation, -and definitions of the terms used here, -see L. +and definitions see L. -If no operation is specified, -git-debrebase launders the branch and rebases the Debian delta queue. -See below. +You should read this manpage in conjunction with +L, +which defines many important terms used here. =head1 PRINCIPAL OPERATIONS @@ -67,7 +66,8 @@ Firstly, checks that the proposed rebase seems to make sense: It is a problem unless the new upstream(s) are fast forward from the previous upstream(s) as found in the current breakwater anchor. -And, in the case of a multi-piece upstream, +And, in the case of a multi-piece upstream +(a multi-component upstream, in dpkg-source terminology), if the pieces are not in the same order, with the same names. If all seems well, unstitches and launders the branch. @@ -90,15 +90,15 @@ just like a normal git-rebase. If you git-rebase --abort, the whole new upstream operation is aborted, -but the laundering will still have been done. +except for the laundering. The are, optionally, in order: =over -=item +=item -The new upstream branch (or commitish). +The new upstream branch (or commit-ish). Default is C. It is a problem if the upstream contains a debian/ directory; @@ -106,10 +106,9 @@ if forced to proceed, git-debrebase will disregard the upstream's debian/ and take (only) the packaging from the current breakwater. -=item +=item Specifies that this is a multi-piece upstream. -(A multi-component upstream, in dpkg-source terminology.) May be repeated. When such a pair is specified, @@ -118,7 +117,7 @@ together, and then use the result as the combined new upstream. For each , -the tree of the +the tree of the becomes the subdirectory in the combined new upstream (supplanting any subdirectory that might be there in @@ -150,14 +149,16 @@ which must be identical to the rev-spec(s) passed to git-debrebase. git-debrebase does not concern itself with source packages so neither helps with this, nor checks it. -L, L and L may be able to help. +L, +L, L and +L may be able to help. This subcommand has -v0 in its name because we are not yet sure that its command line syntax is optimal. We may want to introduce an incompatible replacement syntax under the name C. -=item git-debrebase convert-from-gbp [] +=item git-debrebase convert-from-gbp [] Cnnverts a gbp patches-unapplied branch (not a gbp pq patch queue branch) @@ -167,8 +168,8 @@ This is done by generating a new anchor merge, converting the quilt patches as a delta queue, and dropping the patches from the tree. -The upstream commitish should correspond to -the gbp upstream branch. +The upstream commit-ish should correspond to +the gbp upstream branch, if there is one. It is a problem if it is not an ancestor of HEAD, or if the history between the upstream and HEAD contains commits which make changes to upstream files. @@ -201,6 +202,10 @@ Prints the breakwater tip commitid. If your HEAD branch is not fully laundered, prints the tip of the so-far-laundered breakwater. +=item git-debrebase anchor + +Prints the breakwater anchor commitid. + =item git-debrebase analyse Walks the history of the current branch, @@ -250,7 +255,11 @@ or you will drop all the patches! This section documents the general options to git-debrebase -(ie, the ones which follow git-debrebase). +(ie, the ones which immediately follow +git-debrebase +or +git debrebase +on the command line). Individual operations may have their own options which are docuented under each operation. @@ -291,16 +300,18 @@ because there is nothing to do. The specific instances are discussed in the text for the relvant operation. -=item --anchor= +=item --anchor= -Treats as an anchor, -regardless of what it's actually like. +Treats as an anchor. +This overrides the usual logic which automatically classifies +commits as anchors, pseudomerges, delta queue commits, etc. -(It is a problem for -git-debrebase new-upstream operations -if 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 is the anchor +for the previous upstream version in +git-debrebase new-upstream operations. =item -D @@ -315,30 +326,49 @@ In detail this means: =head2 Establish the current branch's ffq-prev -If it is not yet recorded, +If ffq-prev is not yet recorded, git-debrebase checks that the current branch is ahead of relevant remote tracking branches. +The relevant branches depend on +the current branch (and its +git configuration) +and are as follows: + +=over + +=item + +The branch that git would merge from +(remote..merge, remote..remote); + +=item + +The branch git would push to, if different +(remote..pushRemote etc.); + +=item + +For local dgit suite branches, +the corresponding tracking remote; + +=item + +If you are on C, +remotes/dgit/dgit/sid. + +=back + +The apparently relevant ref names to check are filtered through +branch..ffq-ffrefs, +which is a semicolon-separated list of glob patterns, +each optionally preceded by !; first match wins. -The remote tracking branches checked by default are -obtained from the git config. In each case it is a problem if the local HEAD is behind the checked remote, or if local HEAD has diverged from it. All the checks are done locally using the remote tracking refs: git-debrebase does not fetch anything from anywhere. -git-debrebase checks the branch that git would merge from -(remote..merge, remote..remote) -and the branch git would push to -(remote..pushRemote etc.). -For local dgit suite branches -it checks the corresponding tracking remote. -If you are on C, it checks remotes/dgit/dgit/sid. -The resulting ref names to check are filtered through -branch..ffq-ffrefs, -which is a semicolon-separated list of glob patterns, -each optionally preceded by !; first match wins. - If these checks pass, or are forced, git-debrebse then records the current tip as ffq-prev. @@ -365,4 +395,5 @@ The result is the laundered branch. git-debrebase(1), dgit-maint-rebase(7), -dgit(1) +dgit(1), +gitglossary(7)