git-debrebase: factor out getoptions for subcommand

[dgit.git] / git-debrebase.1.pod

diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index 6168e144dc057e50c96c0c5c7f34747d81373f56..db22fa5d5023baad3e6ec5198de6913e53ce8eba 100644 (file)
--- a/git-debrebase.1.pod
+++ b/git-debrebase.1.pod
@@ -15,11 +15,11 @@ Debian packages based on upstream source code.
 
 This is the command line reference.
 Please read the tutorial
-L<dgit-maint-debrebase(5)>.
+L<dgit-maint-debrebase(7)>.
 For background, theory of operation,
 and definitions see L<git-debrebase(5)>.
 
-You should read this manpage in conjunction with
+You should read this manpage in cojnunction with
 L<git-debrebase(5)/TERMINOLOGY>,
 which defines many important terms used here.
 
@@ -55,12 +55,18 @@ The options for git-rebase must either start with C<-i>,
 or be prececded by C<-->,
 to distinguish them from options for git-debrebase.
 
+It is hazardous to use plain git-rebase on a git-debrebase branch,
+because git-rebase has a tendency to start the rebase
+too far back in history,
+and then drop important commits.
+Soo L<git-debrebase(5)/ILLEGAL OPERATIONS>
+
 =item git-debrebase status
 
-Analyise the current branch,
-both in terms of its conents,
+Analyses the current branch,
+both in terms of its contents,
 and the refs which are relevant to git-debrebase,
-and print a human-readable summary.
+and prints a human-readable summary.
 
 Please do not attempt to parse the output;
 it may be reformatted or reorganised in the future.
@@ -135,6 +141,12 @@ If you git-rebase --abort,
 the whole new upstream operation is aborted,
 except for the laundering.
 
+<new-version>
+may be whole new Debian version, including revision,
+or just the upstream part,
+in which case -1 will be appended
+to make the new Debian version.
+
 The <upstream-details> are, optionally, in order:
 
 =over
@@ -244,6 +256,8 @@ the gbp upstream branch, if there is one.
 It is a snag 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.
+If it is not specified,
+the same algorithm is used as for git-debrebase new-upstream.
 
 It is also a snag if the specified upstream
 has a debian/ subdirectory.
@@ -251,11 +265,20 @@ This check exists to detect certain likely user errors,
 but if this situation is true and expected,
 forcing it is fine.
 
+git-debrebase will try to look for the dgit archive view
+of the most recent release,
+and if it finds it will make a pseduomerge so that
+your new git-debrebase view is appropriately fast forward.
+
 The result is a well-formed git-debrebase interchange branch.
 The result is also fast-forward from the gbp branch.
 
+It is a snag if the new branch looks like it will have diverged,
+just as for a laundering/unstitching call to git-debrebase;
+See L</Establish the current branch's ffq-prev>, below.
+
 Note that it is dangerous not to know whether you are
-dealing with a gbp patches-unappled branch containing quilt patches,
+dealing with a gbp patches-unapplied branch containing quilt patches,
 or a git-debrebase interchange branch.
 At worst,
 using the wrong tool for the branch format might result in
@@ -343,7 +366,7 @@ Turns snag(s) with id <snag-id> into warnings.
 Some troublesome things which git-debrebase encounters
 are B<snag>s.
 (The specific instances are discussed
-in the text for the relvant operation.)
+in the text for the relevant operation.)
 
 When a snag is detected,
 a message is printed to stderr containing the snag id