From 952789d95a825aff6524ec45829ed0d9bfd50f6d Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Mon, 19 Feb 2018 01:03:36 +0000
Subject: [PATCH] git-debrebase(1): wip

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
---
 NOTES.git-debrebase |  5 +---
 git-debrebase.1.pod | 61 ++++++++++++++++++++++++++++-----------------
 2 files changed, 39 insertions(+), 27 deletions(-)

diff --git a/NOTES.git-debrebase b/NOTES.git-debrebase
index 79b6f2b6..5a6ff882 100644
--- a/NOTES.git-debrebase
+++ b/NOTES.git-debrebase
@@ -88,10 +88,7 @@ N. git-debrebase [--noop-ok] record-ffq-prev
 
      does what is described above
 
-2. git-debrebase [--noop-ok] stitch
-
-    makes pseudomerge with ffq-prev
-    deletes ffq-prev
+Re git-debrebase [--noop-ok] stitch
 
     we will teach dgit to do
        git-debrebase stitch
diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index ab6e12ce..ce442daf 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),
-- 
2.30.2