dgit(1): Clarify the non-split-brain --quilt options

Make it clear(er) that all of them expected a dgit view branch.

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

1 files changed, 18 insertions, 11 deletions

diff --git a/dgit.1 b/dgit.1
index b91f28d..5a0eb82 100644
--- a/dgit.1
+++ b/dgit.1
@@ -876,8 +876,8 @@ throw away the existing repo.  Not relevant when pushing to Debian,
 as the Debian server will do this automatically when necessary.
 .TP
 .BR --quilt=linear
-When fixing up source format `3.0 (quilt)' metadata, insist on
-generating a linear patch stack: one new patch for each relevant
+With format `3.0 (quilt)', insist on
+a linear patch stack: one new patch for each relevant
 commit.
 If such a stack cannot be generated, fail.
 This is the default for Debian.
@@ -888,8 +888,9 @@ and pseudomerges,
 with as ancestor a patches-applied branch.
 .TP
 .BR --quilt=try-linear
-When fixing up source format `3.0 (quilt)' metadata, prefer to
-generate a linear patch stack
+With format `3.0 (quilt)',
+prefer
+a linear patch stack
 (as with --quilt=linear)
 but if that doesn't seem possible,
 try to generate a single squashed patch for all the changes made in git
@@ -897,7 +898,8 @@ try to generate a single squashed patch for all the changes made in git
 This is not a good idea for an NMU in Debian.
 .TP
 .BR --quilt=smash
-When fixing up source format `3.0 (quilt)' metadata,
+With format `3.0 (quilt)',
+assume patches-applied (as obtained from dgit clone) and
 generate a single additional patch for all the changes made in git.
 This is not a good idea for an NMU in Debian.
 
@@ -908,7 +910,8 @@ nor make changes in debian/patches,
 it will remain true.)
 .TP
 .BR --quilt=single
-When fixing up source format `3.0 (quilt)' metadata,
+With format `3.0 (quilt)',
+assume patches-applied (as obtained from dgit clone),
 delete all the existing patches, and then
 generate a single patch for all the changes made in git.
 This is not a good idea for an NMU in Debian.
@@ -923,17 +926,21 @@ that dpkg-source appears to accept
 but which become corrupted when people later try to modify them.
 .TP
 .BR --quilt=nofix
-Check whether source format `3.0 (quilt)' metadata would need fixing
-up, but, if it does, fail.  You must then fix the metadata yourself
+With format `3.0 (quilt)',
+assume patches-applied (as obtained from dgit clone), and
+check that the patch metadata is up to date.
+If it isn't, fail; you must then fix the metadata yourself
 somehow before pushing.  (NB that dpkg-source --commit will not work
 because the dgit git tree does not have a
 .B .pc
 directory.)
 .TP
 .BR --quilt=nocheck " | " --no-quilt-fixup
-Do not check whether source format `3.0 (quilt)' metadata needs
-fixing up.  If you use this option and the metadata did in fact need
-fixing up, dgit push will fail.
+With format `3.0 (quilt)',
+assume that the tree is patches-applied (as obtained from dgit clone),
+and \fIassume\fR that the patch metadata is up to date.
+If you use this option and the patch metadata is out of date,
+dgit push will fail.
 .TP
 .BR -- [ quilt= ] gbp " | " -- [ quilt= ] dpm " | " --quilt=unapplied " | " -- [ quilt= ] baredebian [ +git | +tarball ]
 Tell dgit that you are using a nearly-dgit-compatible git branch,