dgit.1: Clarify the --clean= options' documentation. Closes:#800054.

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

diff --git a/debian/changelog b/debian/changelog
index 7bc0a110808d737f33ae0c9b85f3d09ba117b2a4..18e3e3e4f11ae072306b350f8683e945e4f735d9 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -50,6 +50,7 @@ dgit (1.5~~) unstable; urgency=medium
 
   Documentation:
   * Document the dgit-distro.DISTRO.quilt-mode config setting.
 
   Documentation:
   * Document the dgit-distro.DISTRO.quilt-mode config setting.

+  * Clarify the --clean= options' documentation.  Closes:#800054.

 
   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

diff --git a/dgit.1 b/dgit.1
index 13666ea432cf08f14d33abf738d562fd0c1eba06..a01590601fe7f9cb28b1f5bc0a3d8858bd2ceb24 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -276,46 +276,53 @@ rather than looking in debian/control or debian/changelog.
 Valid with dgit fetch and dgit pull, only.
 .TP
 .BR --clean=git " | " -wg
 Valid with dgit fetch and dgit pull, only.
 .TP
 .BR --clean=git " | " -wg

-The source tree should be cleaned, before building a source package
-with one of the build options, using
-.BR "git clean -xdf" .
-This will delete all files which are not tracked by git.  Also, -wg
-causes dgit to pass
-.B -nc
-to dpkg-buildpackage, which prevents the package's own clean target
-from being run.
-
---clean=git is useful when the package's clean target is troublesome;
-the downside is simply that git clean may delete files you forgot to
-git add.  --clean=git can also avoid needing the build-dependencies.
+Use
+.BR "git clean -xdf"
+to clean the working tree,
+rather than running the package's rules clean target.
+
+This will delete all files which are not tracked by git.
+(Including any files you forgot to git add.)
+
+.BI --clean= ...
+options other than dpkg-source
+are useful when the package's clean target is troublesome, or
+to avoid needing the build-dependencies.

 .TP
 .BR --clean=git-ff " | " -wgf
 .TP
 .BR --clean=git-ff " | " -wgf

-The source tree should be cleaned, before building a source package
-with one of the build options, using
-.BR "git clean -xdff" .
-This is like
-"git clean -xdf"
+Use
+.BR "git clean -xdff"
+to clean the working tree.
+Like
+git clean -xdf

 but it also removes any subdirectories containing different git
 trees (which only unusual packages are likely to create).
 .TP
 .BR --clean=check " | " -wc
 Merely check that the tree is clean (does not contain uncommitted
 but it also removes any subdirectories containing different git
 trees (which only unusual packages are likely to create).
 .TP
 .BR --clean=check " | " -wc
 Merely check that the tree is clean (does not contain uncommitted

-files), before building a source package.
+files).
+Avoids running rules clean,
+and can avoid needing the build-dependencies.

 .TP
 .BR --clean=none " | " -wn
 .TP
 .BR --clean=none " | " -wn

-Do not clean the tree before building a source package.  If there are
+Do not clean the tree, nor check that it is clean.
+Avoids running rules clean,
+and can avoid needing the build-dependencies.
+If there are

 files which are not in git, or if the build creates such files, a
 subsequent dgit push will fail.
 .TP
 .BR --clean=dpkg-source " | " -wd
 Use dpkg-buildpackage to do the clean, so that the source package
 is cleaned by dpkg-source running the package's clean target.
 files which are not in git, or if the build creates such files, a
 subsequent dgit push will fail.
 .TP
 .BR --clean=dpkg-source " | " -wd
 Use dpkg-buildpackage to do the clean, so that the source package
 is cleaned by dpkg-source running the package's clean target.

-This is the default.  It requires the package's build dependencies.
+This is the default.
+Requires the package's build dependencies.

 .TP
 .BR --clean=dpkg-source-d " | " -wdd
 Use
 .B dpkg-buildpackage -d
 .TP
 .BR --clean=dpkg-source-d " | " -wdd
 Use
 .B dpkg-buildpackage -d

-to do the clean, so that the source package
+to do the clean,
+so that the source package

 is cleaned by dpkg-source running the package's clean target.
 The build-dependencies are not checked (due to
 .BR -d ),
 is cleaned by dpkg-source running the package's clean target.
 The build-dependencies are not checked (due to
 .BR -d ),