git-debrebase(1): wip

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

1 files changed, 38 insertions, 23 deletions

diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index ab6e12c..ce442da 100644
--- a/git-debrebase.1.pod
+++ b/git-debrebase.1.pod
@@ -2,6 +2,11 @@
 
 git-debrebase - delta queue rebase tool for Debian packaging
 
+=head1 SYNOPSYS
+
+ git-debrebase [<options...>] [-- <git-rebase options...>]
+ git-debrebase [<options...>] <operation> [<operation options...>
+
 =head1 INTRODUCTION
 
 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
 L<dgit-maint-debrebase(5)>.
-
 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
@@ -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>.
+
+=back
+
+=head1 UNDERLYING AND SUPPLEMENTARY OPERATIONS
+
+=over
+
+=item git-debrebase breakwater
+
+Prints the breakwater tip commitid.
+Fails if your HEAD branch is not laundered.
+
 =back
 
 =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
 (remote.<branch>.merge, remote.<branch>.remote)
-and the branch we would push to
+and the branch git would push to
 (remote.<branch>.pushRemote etc.).
 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
 branch.<branch>.ffq-ffrefs,
 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
+git-debrebase
+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
-
-=over
-
-=item git-debrebase breakwater
-
-Prints the breakwater tip commitid.
-Fails if your HEAD branch is not laundered.
-
-=back
-
 =head1 SEE ALSO
 
 git-debrebase(1),