From f01b34a46e26e519242edf010958d98534fa42ab Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 12 Apr 2018 00:25:15 +0100 Subject: git-debrebase(1): Improvements from Sean Suggested in or prompted by Sean's mail of 28th March. Signed-off-by: Ian Jackson --- git-debrebase.1.pod | 92 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 57 insertions(+), 35 deletions(-) (limited to 'git-debrebase.1.pod') diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod index ed33b79..9140702 100644 --- a/git-debrebase.1.pod +++ b/git-debrebase.1.pod @@ -20,10 +20,6 @@ For background, theory of operation, and definitions of the terms used here, see L. -If no operation is specified, -git-debrebase launders the branch and rebases the Debian delta queue. -See below. - =head1 PRINCIPAL OPERATIONS =over @@ -67,7 +63,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 +87,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 +103,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 +114,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 +146,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 +165,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. @@ -254,7 +252,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. @@ -295,14 +297,14 @@ 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, +Treats as an anchor, regardless of what it's actually like. (It is a problem for git-debrebase new-upstream operations -if is the previous anchor to be used, +if is the previous anchor to be used, because treating an arbitrary commit as an anchor means forgoing upstream coherency checks.) @@ -319,30 +321,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. @@ -369,4 +390,5 @@ The result is the laundered branch. git-debrebase(1), dgit-maint-rebase(7), -dgit(1) +dgit(1), +gitglossary(7) -- cgit v1.2.3