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

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index a01590601fe7f9cb28b1f5bc0a3d8858bd2ceb24..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
 .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
 .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,
 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.
 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
 .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).
 
 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
 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.
 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
 .BI debian/ version
 for the maintainer view, and the dgit tag
 .BI archive/debian/ version


@@ -507,6 +524,50 @@ Passed to dpkg-genchanges (eventually).
 Specifies a single additional option to pass, eventually, to
 dpkg-genchanges.
 .TP
 Specifies a single additional option to pass, eventually, to
 dpkg-genchanges.
 .TP

+.RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."
+Specifies a single additional option to pass to
+.BR curl ,
+.BR dput ,
+.BR debsign ,
+.BR dpkg-source ,
+.BR dpkg-buildpackage ,
+.BR dpkg-genchanges ,
+.BR sbuild ,
+.BR ssh ,
+.BR dgit ,
+.BR gbp-pq ,
+.BR gbp-build ,
+or
+.BR mergechanges .
+Can be repeated as necessary.
+
+Use of this ability should not normally be necessary.
+It is provided for working around bugs,
+or other unusual situations.
+If you use these options,
+you may violate dgit's assumptions
+about the behaviour of its subprograms
+and cause lossage.
+
+For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild,
+the option applies only when the program is invoked directly by dgit.
+Usually, for passing options to dpkg-genchanges, you should use
+.BR --ch: \fIoption\fR.
+
+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.
+
+NB that --gpg:option is not supported (because debsign does not
+have that facility).
+But see
+.B -k
+and the
+.B keyid
+distro config setting.
+.TP

 .RI \fB--curl=\fR program " | \fB--dput=\fR" program  " |..."
 Specifies alternative programs to use instead of
 .BR curl ,
 .RI \fB--curl=\fR program " | \fB--dput=\fR" program  " |..."
 Specifies alternative programs to use instead of
 .BR curl ,


@@ -568,42 +629,6 @@ git to access dgit-repos, only git's idea of what ssh to use (eg,
 .BR GIT_SSH )
 is relevant.
 .TP
 .BR GIT_SSH )
 is relevant.
 .TP

-.RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."
-Specifies a single additional option to pass to
-.BR curl ,
-.BR dput ,
-.BR debsign ,
-.BR dpkg-source ,
-.BR dpkg-buildpackage ,
-.BR dpkg-genchanges ,
-.BR sbuild ,
-.BR ssh ,
-.BR dgit ,
-.BR gbp-pq ,
-.BR gbp-build ,
-or
-.BR mergechanges .
-Can be repeated as necessary.
-
-For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild,
-this applies only when the program is invoked directly by dgit.
-Usually, for passing options to dpkg-genchanges, you should use
-.BR --ch: \fIoption\fR.
-
-Specifying --git 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.
-
-NB that --gpg:option is not supported (because debsign does not
-have that facility).
-But see
-.B -k
-and the
-.B keyid
-distro config setting.
-.TP

 .BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
 Specifies that the suite to be operated on is part of distro
 .IR distro .
 .BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
 Specifies that the suite to be operated on is part of distro
 .IR distro .