Provide --gbp and --dpm as aliases for --quilt=gbp and --quilt=dpm.

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index 437a5740fde1716ded85e0d3bd13ee7ec942f047..99ae90bf0b6bf043328f113e28747eece25b3501 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


@@ -429,20 +445,24 @@ Do not check whether up 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.
 .TP
 fixing up.  If you use this option and the metadata did in fact need
 fixing up, dgit push will fail.
 .TP

-.BR --quilt=gbp " | " --quilt=dpm " | " --quilt=unapplied
+.BR -- [ quilt= ] gbp " | " -- [ quilt= ] dpm " | " --quilt=unapplied

 Tell dgit that you are using a nearly-dgit-compatible git branch,
 aka a
 .BR "maintainer view" ,
 and
 do not want your branch changed by dgit.
 
 Tell dgit that you are using a nearly-dgit-compatible git branch,
 aka a
 .BR "maintainer view" ,
 and
 do not want your branch changed by dgit.
 

-.B --quilt=gbp
+.B --gbp
+(short for
+.BR --quilt=gbp )

 is for use with git-buildpackage.
 Your HEAD is expected to be
 a patches-unapplied git branch, except that it might contain changes
 to upstream .gitignore files.  This is the default for dgit gbp-build.
 
 is for use with git-buildpackage.
 Your HEAD is expected to be
 a patches-unapplied git branch, except that it might contain changes
 to upstream .gitignore files.  This is the default for dgit gbp-build.
 

-.B --quilt=dpm
+.B --dpm
+(short for
+.BR --quilt=dpm )

 is for use with git-dpm.
 Your HEAD is expected to be
 a patches-applied git branch,
 is for use with git-dpm.
 Your HEAD is expected to be
 a patches-applied git branch,


@@ -453,27 +473,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).
 
 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-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.
 .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
 
 .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.
 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
 and you aren't too lucky, dgit will notice the problem and stop,
 with a useful hint. 
 .TP


@@ -506,6 +529,11 @@ Passed to dpkg-genchanges (eventually).
 .RI \fB--ch:\fR option
 Specifies a single additional option to pass, eventually, to
 dpkg-genchanges.
 .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
 .TP
 .RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."
 Specifies a single additional option to pass to


@@ -541,7 +569,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.
 
 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).
 
 NB that --gpg:option is not supported (because debsign does not
 have that facility).


@@ -935,6 +963,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),
 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),
 \fBcurl\fP(1),
 \fBdput\fP(1),
 \fBdebsign\fP(1),