X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;ds=sidebyside;f=dgit.1;h=993d50b2454683ceff2268d5a9789724264ece86;hb=6c32ca2f056fc65bfc1aedbac6cdccdec0df0e01;hp=ccf1ea597e111bb447ca86795992ae67f7883001;hpb=0457c2d771ef6fe6c0883344add9dd4da0c60917;p=dgit.git

diff --git a/dgit.1 b/dgit.1
index ccf1ea59..993d50b2 100644
--- a/dgit.1
+++ b/dgit.1
@@ -538,7 +538,12 @@ This will delete all files which are not tracked by git.
 options other than dpkg-source
 are useful when the package's clean target is troublesome, or
 to avoid needing the build-dependencies.
-.TP
+
+dgit will only actually clean the tree if it needs to
+(because it needs to build the source package
+or binaries from your working tree).
+Otherwise any untracked files will be simply ignored.
+p.TP
 .BR --clean=git-ff " | " -wgf
 Use
 .BR "git clean -xdff"
@@ -548,11 +553,22 @@ 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
+.BR --clean=check " | " --clean=check,ignores " | " -wc " | " -wci
 Merely check that the tree is clean (does not contain uncommitted
 files).
 Avoids running rules clean,
 and can avoid needing the build-dependencies.
+
+With
+.BR ,ignores
+or
+.BR -wci ,
+untracked files covered by .gitignore are tolerated,
+so only files which show up as
+.B ?
+in git status
+(ie, ones you maybe forgot to git add)
+are treated as a problem.
 .TP
 .BR --clean=none " | " -wn
 Do not clean the tree, nor check that it is clean.
@@ -562,21 +578,50 @@ 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
+.BR --clean=dpkg-source "[" -d "] | " -wd " | " -wdd
 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.
-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
-is cleaned by dpkg-source running the package's clean target.
-The build-dependencies are not checked (due to
-.BR -d ),
+--clean=dpkg-source is the default.
+
+Without the extra
+.BR d ,
+requires the package's build dependencies.
+
+With
+.BR ... -d
+or
+.BR -wdd ,
+the build-dependencies are not checked
+(due to passing
+.BR -d
+to dpkg-buildpackage),
 which violates policy, but may work in practice.
+
+The rules clean target will only be run if it is needed:
+when dgit is going to build source or binary packages
+from your working tree,
+rather than from your git branch
+(for example because of --include-dirty
+or because the binary package build uses your working tree).
+
+In all cases,
+dgit will check that there are (after rules clean, if applicable) no
+untracked un-ignored files,
+in case these are files you forgot to git add.
+(Except that this check is not done
+for a `3.0 (quilt)' package
+when dgit has to apply patches, dirtily, to the working tree.)
+If your package does not have a good .gitignore
+you will probably need --clean=dpkg-source,no-check aka -wdn.
+.TP
+.BR --clean=dpkg-source "[" -d "]" ,no-check " | " -wdn " | " -wddn
+Like --clean=dpkg-source, but
+does not care about untracked un-ignored files.
+.TP
+.BR --clean=dpkg-source "[" -d "]" ,all-check " | " -wda " | " -wdda
+Like --clean=dpkg-source, but
+fails even on ignored untracked files.
+This could perhaps be used to detect bugs in your rules clean target.
 .TP
 .BR -N " | " --new
 The package is or may be new in this suite.  Without this, dgit will
@@ -1034,6 +1079,24 @@ and the
 .B keyid
 distro config setting.
 .TP
+.RI \fB--curl!:\fR option " | \fB--dput!:\fR" option " |..."
+Specifies an option to remove from the command line for
+a program called by dgit, as for
+\fB--\fR\fIprogram\fI\fB:\fR\fIoption\fR
+(and the same caveats apply).
+
+Any options or arguments exactly identical to
+.I option
+are removed.
+(It is not an error if there were none.)
+
+This can only be used to delete options
+which are always passed by default by dgit,
+or to undo a previous
+\fB--\fR\fIprogram\fI\fB:\fR\fIoption\fR.
+It cannot be used to override option(s) dynamically
+decided on by dgit.
+.TP
 .RI \fB--curl=\fR program " | \fB--dput=\fR" program  " |..."
 Specifies alternative programs to use instead of
 .BR curl ,
@@ -1225,7 +1288,7 @@ but ignored if the value does not make sense to this version of dgit.
 Setting both .clean-mode and .clean-mode-newer is useful
 to provide a single git config compatible with different dgit versions.
 .TP
-.BR dgit-distro. \fIdistro\fR .quilt-
+.BR dgit-distro. \fIdistro\fR .quilt-mode
 One of the values for the command line --quilt= option; used if
 --quilt is not specified.
 .TP