Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
* Clarify the --clean= options' documentation. Closes:#800054.
* Discourage use of the --PROGRAM:OPTION escape hatch. (Apropos
of various bug reports including #800060.)
* 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
Bugfixes:
* When cleaning up after failed clone, stat the to-be-cleaned-up
.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
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
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 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