X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=cd2075f18ced11387e9f187ba795862ec63439c6;hp=437a5740fde1716ded85e0d3bd13ee7ec942f047;hb=dbb9a7586bd73d7e3b5ec1bdc17adebe7f0a181c;hpb=9c83425fc20526e6bb7a50ce5a467fa8fa0c7600

diff --git a/dgit.1 b/dgit.1
index 437a5740..cd2075f1 100644
--- 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,27 +469,30 @@ 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
-convert your git branch into the right form,
-and dgit push will push the
+With --quilt=gbp|dpm|unapplied,
+dgit push (or precursors like quilt-fixup and build) will automatically
+generate a conversion of your git branch into the right form.
+dgit push will push the
 dgit-compatible form (the
 .BR "dgit view" )
 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
 for the dgit view.
+dgit quilt-fixup will merely do some checks,
+and cache the maintainer view.
 
 .B If you have a branch like this it is essential to specify the appropriate --quilt= option!
 This is because it is not always possible to tell: a patches-unapplied
-git branch of a package with one patch, for example, looks just the
-same as a patches-applied branch where the user has used git revert to
+git branch of a package with one patch, for example, looks very like
+a patches-applied branch where the user has used git revert to
 undo the patch, expecting to actually revert it.
-If you fail to specify the right \-\-quilt option,
+However, if you fail to specify the right \-\-quilt option,
 and you aren't too lucky, dgit will notice the problem and stop,
 with a useful hint. 
 .TP
@@ -506,6 +525,11 @@ Passed to dpkg-genchanges (eventually).
 .RI \fB--ch:\fR option
 Specifies a single additional option to pass, eventually, to
 dpkg-genchanges.
+
+Options which are safe to pass include
+.BR "-si -sa -sd -C" .
+
+For other options the caveat below applies.
 .TP
 .RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."
 Specifies a single additional option to pass to
@@ -541,7 +565,7 @@ Specifying --git is not effective for some lower-level read-only git
 operations performed by dgit, and also not when git is invoked by
 another program run by dgit.
 
-See notes above regarding ssh and dgit.
+See notes below regarding ssh and dgit.
 
 NB that --gpg:option is not supported (because debsign does not
 have that facility).
@@ -935,6 +959,7 @@ fetches may result in subsequent actions being different.  Doing a
 non-dry-run dgit fetch first will help.
 .SH SEE ALSO
 \fBdgit\fP(7),
+\fBdgit-maint-merge\fP(7),
 \fBcurl\fP(1),
 \fBdput\fP(1),
 \fBdebsign\fP(1),