chiark / gitweb /
git-debrebase(1): Improvements from Sean
authorIan Jackson <ijackson@chiark.greenend.org.uk>
Wed, 11 Apr 2018 23:25:15 +0000 (00:25 +0100)
committerIan Jackson <ijackson@chiark.greenend.org.uk>
Sat, 16 Jun 2018 15:07:00 +0000 (16:07 +0100)
Suggested in or prompted by Sean's mail of 28th March.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
git-debrebase.1.pod

index ed33b79..9140702 100644 (file)
@@ -20,10 +20,6 @@ For background, theory of operation,
 and definitions of the terms used here,
 see L<git-debrebase(5)>.
 
-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 <upstream-details> are, optionally, in order:
 
 =over
 
-=item <upstream-commitish>
+=item <upstream-commit-ish>
 
-The new upstream branch (or commitish).
+The new upstream branch (or commit-ish).
 Default is C<upstream>.
 
 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 <piece-name> <piece-upstream-commitish>
+=item <piece-name> <piece-upstream-commit-ish>
 
 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 <piece-name>,
-the tree of the <piece-upstream-commitish>
+the tree of the <piece-upstream-commit-ish>
 becomes the subdirectory <piece-name>
 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<git-archive(1)>, L<dgit(1)> and L<gbp(1)> may be able to help.
+L<git-deborig(1)>,
+L<git-archive(1)>, L<dgit(1)> and
+L<gbp-import-orig(1)> 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<new-upstream>.
 
-=item git-debrebase convert-from-gbp [<upstream-commitish>]
+=item git-debrebase convert-from-gbp [<upstream-commit-ish>]
 
 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=<commitish>
+=item --anchor=<commit-ish>
 
-Treats <commitish> as an anchor,
+Treats <commit-ish> as an anchor,
 regardless of what it's actually like.
 
 (It is a problem for
 git-debrebase new-upstream operations
-if <commitish> is the previous anchor to be used,
+if <commit-ish> 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.<branch>.merge, remote.<branch>.remote);
+
+=item
+
+The branch git would push to, if different
+(remote.<branch>.pushRemote etc.);
+
+=item
+
+For local dgit suite branches,
+the corresponding tracking remote;
+
+=item
+
+If you are on C<master>,
+remotes/dgit/dgit/sid.
+
+=back
+
+The apparently relevant ref names to check are filtered through
+branch.<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.<branch>.merge, remote.<branch>.remote)
-and the branch git would push to
-(remote.<branch>.pushRemote etc.).
-For local dgit suite branches
-it checks the corresponding tracking remote.
-If you are on C<master>, it checks remotes/dgit/dgit/sid.
-The resulting ref names to check are filtered through
-branch.<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)