From 430c0a2bccc7427a981310da73061d2d4fe52bab Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Sun, 9 Oct 2016 12:54:24 +0100
Subject: [PATCH] dgit.1: Clarify the --clean= options' documentation. 
 Closes:#800054.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
---
 debian/changelog |  1 +
 dgit.1           | 49 +++++++++++++++++++++++++++---------------------
 2 files changed, 29 insertions(+), 21 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index 7bc0a110..18e3e3e4 100644
--- 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.
+  * Clarify the --clean= options' documentation.  Closes:#800054.
 
   Bugfixes:
   * When cleaning up after failed clone, stat the to-be-cleaned-up
diff --git a/dgit.1 b/dgit.1
index 13666ea4..a0159060 100644
--- 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
-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
-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
-files), before building a source package.
+files).
+Avoids running rules clean,
+and can avoid needing the build-dependencies.
 .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.
-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
-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 ),
-- 
2.30.2