dgit.1: Document the expected form of HEAD for each --quilt= mode.

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

diff --git a/debian/changelog b/debian/changelog
index 83c602c122835722617a58f22d0b60aa25435851..4bc6df0d7585f0f66e16953aa9c62ec4469371f4 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -55,6 +55,7 @@ dgit (1.5~~) unstable; urgency=medium
   * Clarify the --clean= options' documentation.  Closes:#800054.
   * Discourage use of the --PROGRAM:OPTION escape hatch.  (Apropos
     of various bug reports including #800060.)
+  * Document the expected form of HEAD for each --quilt= mode.
 
   Bugfixes:
   * When cleaning up after failed clone, stat the to-be-cleaned-up

diff --git a/dgit.1 b/dgit.1
index 437a5740fde1716ded85e0d3bd13ee7ec942f047..677da279e0d58e2da4ba6f437a89063478ec4115 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -402,19 +402,35 @@ 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.  If such a stack cannot be generated,
-fail.  This is the default for Debian.
+generating 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.
+
+HEAD should be a series of plain commits
+(not touching debian/patches/),
+and pseudomerges,
+with as ancestor a patches-applied branch.
 .TP
 .BR --quilt=auto
 When fixing up source format `3.0 (quilt)' metadata, prefer to
-generate a linear patch stack, but if that doesn't seem possible,
-generate a single squashed patch for all the changes made in git.
+generate a linear patch stack
+(as with --quilt=auto)
+but if that doesn't seem possible,
+try to generate a single squashed patch for all the changes made in git
+(as with --quilt=smash).
 This is not a good idea for an NMU in Debian.
 .TP
 .BR --quilt=smash
 When fixing up source format `3.0 (quilt)' metadata,
-generate a single squashed patch for all the changes made in git.
+generate a single additional patch for all the changes made in git.
 This is not a good idea for an NMU in Debian.
+
+(If HEAD has any in-tree patches already, they must apply cleanly.
+This will be the case for any trees produced by dgit fetch or clone;
+if you do not change the upstream version
+nor make changes in debian/patches,
+it will remain true.)
 .TP
 .BR --quilt=nofix
 Check whether source format `3.0 (quilt)' metadata would need fixing
@@ -453,7 +469,8 @@ specifies that your HEAD is a patches-unapplied git branch (and
 that any changes to upstream .gitignore files are represented as
 patches in debian/patches).
 
-Instead, dgit quilt-fixup and dgit-push will automatically
+With --quilt=gbp|dpm|unapplied,
+dgit quilt-fixup and dgit-push will automatically
 convert your git branch into the right form,
 and dgit push will push the
 dgit-compatible form (the
@@ -462,7 +479,7 @@ to the dgit git server.
 The dgit view will be visible to you
 in the dgit remote tracking branches, but your own branch will
 not be modified.
-dgit will create a tag
+dgit push will create a tag
 .BI debian/ version
 for the maintainer view, and the dgit tag
 .BI archive/debian/ version