documentation style: "appropriate configuration" as a mass noun

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

diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod
index d39ad9484986fb022e98e735a030d91f6e136063..c30b124dea9d7cf254107f32827a17fc9a4e2682 100644 (file)
--- a/git-debrebase.5.pod
+++ b/git-debrebase.5.pod
@@ -146,7 +146,7 @@ See L</STITCHING, PSEUDO-MERGES, FFQ RECORD>.
 
 git-debrebase has one primary branch,
 the B<interchange branch>.
-This branch is found on Debian contributor's workstations
+This branch is found on Debian contributors' workstations
 (typically, a maintainer would call it B<master>),
 in the Debian dgit git server as the suite branch (B<dgit/dgit/sid>)
 and on other git servers which support Debian work
@@ -175,7 +175,7 @@ the upstream commits).
 The breakwater does not contain any representation of
 the delta queue (not even debian/patches).
 The part of the breakwater processed by git-debrebase
-is the part since the most reecent B<anchor>,
+is the part since the most recent B<anchor>,
 which is usually a special merge generated by git-debrebase.
 
 When working, locally,
@@ -190,7 +190,7 @@ and the user's work
 can later be
 stitched into the fast-forwarding interchange form.
 
-An unstitched branch may be in
+An unstitched branch may be in the
 B<laundered>
 state,
 which means it has a more particular special form
@@ -255,7 +255,7 @@ a representation of the delta queue:
 =item Delta queue commits
 
 Zero or more single-parent commits
-contaioning only changes to upstream files.
+containing only changes to upstream files.
 
 =back
 
@@ -266,7 +266,7 @@ branch state is also B<rebasing>.
 It has the same contents as the laundered state,
 except that it may contain,
 additionally,
-in B<in any order but after the breakwater>:
+B<in any order but after the breakwater>:
 
 =over
 
@@ -378,8 +378,11 @@ from the interchange branch and no pseudomerge is needed.
 When ffq-prev is not present,
 C<refs/debrebase-last/B> records some ancestor of refs/B,
 (usually, the result of last stitch).
-This can be used to quickly determine whether refs/B
-is being maintained in git-debrebase form.
+This is used for status printing and some error error checks -
+especially for printing guesses about what a problem is.
+To determine whether a branch
+is being maintained in git-debrebase form
+it is necessary to walk its history.
 
 =head1 OTHER MERGES
 
@@ -416,7 +419,7 @@ so we can at least detect unsupported merges.
 
 =head1 LEGAL OPERATIONS
 
-The following basic operations follows from this model
+The following basic operations follow from this model
 (refer to the diagram above):
 
 =over
@@ -469,7 +472,7 @@ so that git log shows the packaging history.)
 =item Stitch 
 
 Make a pseudomerge,
-whose contributing parent to is the unstitched branch
+whose contributing parent is the unstitched branch
 and
 whose overwritten parent is ffq-prev,
 consuming ffq-prev in the process
@@ -480,7 +483,7 @@ or perhaps a laundered branch with a quilt patch addition commit.
 =item Commit quilt patches
 
 To generate a tree which can be represented as a
-3.0 (quilt) .dsc source packages,
+3.0 (quilt) .dsc source package,
 the delta queue must be reified inside the git tree
 in B<debian/patches/>.
 These patch files can be stripped out and/or regenerated as needed.
@@ -512,7 +515,7 @@ For these reasons,
 it is better to use git-debrebase and
 let it choose the base
 for your rebase.
-If you do realise you have make this mistake,
+If you do realise you have made this mistake,
 it is best to use the reflog to recover to a suitable
 good previous state.
 
@@ -527,6 +530,21 @@ If you add patches your work is likely to be discarded.
 Instead of editing patches,
 use git-debrebase to edit the corresponding commits.
 
+=item Renaming (etc.) branch while unstitched
+
+The previous HEAD,
+which will be pseudomerged over
+by operations like git-debrebase stitch,
+is recorded in a ref name dervied from your branch name.
+
+If you rename unstitched branches,
+this information can get out of step.
+
+Conversely,
+creating a new branch from an unstitched branch
+is good for making a branch to play about in,
+but the result cannot be stitched.
+
 =back
 
 =head1 COMMIT MESSAGE ANNOTATIONS
@@ -536,27 +554,31 @@ in the messages of commits it generates.
 
 The general form is
 
-  [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
+  [git-debrebase COMMIT-TYPE [ ARGS...]: PROSE, MORE PROSE]
 
 git-debrebase treats anything after the colon as a comment,
 paying no attention to PROSE.
 
 The full set of annotations is:
-  [git-debrebase: split mixed commit, debian part]
-  [git-debrebase: split mixed commit, upstream-part]
-  [git-debrebase: convert dgit import, debian changes]
+  [git-debrebase split: mixed commit, debian part]
+  [git-debrebase split: mixed commit, upstream-part]
+  [git-debrebase onvert dgit import: debian changes]
   [git-debrebase anchor: convert dgit import, upstream changes]
 
   [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
   [git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge]
-  [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
-  [git-debrebase: export and commit patches]
+  [git-debrebase changelog: new upstream NEW-UPSTREAM-VERSION]
+  [git-debrebase make-patches: export and commit patches]
 
   [git-debrebase convert-from-gbp: drop patches]
   [git-debrebase anchor: declare upstream]
   [git-debrebase pseudomerge: stitch]
 
+  [git-debrebase merged-breakwater: constructed from vanilla merge]
+
   [git-debrebase convert-to-gbp: commit patches]
+  [git-debrebase convert-from-dgit-view upstream-import-convert: VERSION]
+  [git-debrebase convert-from-dgit-view drop-patches]
 
 Only anchor merges have the C<[git-debrebase anchor: ...]> tag.
 Single-parent anchors are not generated by git-debrebase,