|author||Ian Jackson <firstname.lastname@example.org>||2018-04-12 00:25:15 +0100|
|committer||Ian Jackson <email@example.com>||2018-06-16 16:07:00 +0100|
git-debrebase(1): Improvements from Sean
Suggested in or prompted by Sean's mail of 28th March. Signed-off-by: Ian Jackson <firstname.lastname@example.org>
1 files changed, 57 insertions, 35 deletions
diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index ed33b79..9140702 100644
@@ -20,10 +20,6 @@ For background, theory of operation,
and definitions of the terms used here,
-If no operation is specified,
-git-debrebase launders the branch and rebases the Debian delta queue.
=head1 PRINCIPAL OPERATIONS
@@ -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:
-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-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
-(ie, the ones which follow git-debrebase).
+(ie, the ones which immediately follow
+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.
-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
+and are as follows:
+The branch that git would merge from
+The branch git would push to, if different
+For local dgit suite branches,
+the corresponding tracking remote;
+If you are on C<master>,
+The apparently relevant ref names to check are filtered through
+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
-and the branch git would push to
-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
-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.