Diffstat (limited to 'git-debrebase.1.pod')
1 files changed, 38 insertions, 23 deletions
diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index ab6e12c..ce442da 100644
@@ -2,6 +2,11 @@
git-debrebase - delta queue rebase tool for Debian packaging
+ git-debrebase [<options...>] [-- <git-rebase options...>]
+ git-debrebase [<options...>] <operation> [<operation options...>
git-debrebase is a tool for representing in git,
@@ -11,11 +16,14 @@ Debian packages based on upstream source code.
This is the command line reference.
Please read the tutorial
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
@@ -142,6 +150,22 @@ 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.
+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>.
+=head1 UNDERLYING AND SUPPLEMENTARY OPERATIONS
+=item git-debrebase breakwater
+Prints the breakwater tip commitid.
+Fails if your HEAD branch is not laundered.
=head1 UNSTITCHING AND LAUNDERING
@@ -151,24 +175,25 @@ In detail this means:
=head2 Establish the current branch's ffq-prev
-If it is not yet recorded, we
-check that the current branch is ahead of relevant
+If it is not yet recorded,
+git-debrebase checks that the current branch is ahead of relevant
remote tracking branches.
The remote tracking branches checked by default are
obtained from the git config.
-In each case it is a problem if we are behind the checked remote,
-or if we have diverged from it.
-All the checks are local:
+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.
-We check the branch we would merge from
+git-debrebase checks the branch that git would merge from
-and the branch we would push to
+and the branch git would push to
For local dgit suite branches
-we check the corresponding tracking remote.
-If we are on C<master>, we check remotes/dgit/dgit/sid.
+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,
@@ -176,11 +201,12 @@ each optionally preceded by !; first match wins.
If these checks pass,
or are forced,
-we then record the current tip as ffq-prev.
+git-debrebse then records the current tip as ffq-prev.
=head2 Examine the branch
-Analyse the current HEAD's history to find the anchor
+analyses the current HEAD's history to find the anchor
in its breakwater,
and the most recent breakwater tip.
@@ -195,17 +221,6 @@ are dropped.
This rewrite will always succeed, by construction.
The result is the laundered branch.
-=head1 UNDERLYING AND SUPPLEMENTARY OPERATIONS
-=item git-debrebase breakwater
-Prints the breakwater tip commitid.
-Fails if your HEAD branch is not laundered.
=head1 SEE ALSO