X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=d23dde01384c166d71717f2955c104335a3f699d;hp=1ee02301ffa02ffe18e22975dd0102599a9f73ec;hb=fe1e06de2358fc0788604ada99baa5752c1e0e62;hpb=601645922a2dd91735da980227c7bf4198c2071b

diff --git a/dgit.1 b/dgit.1
index 1ee02301..d23dde01 100644
--- a/dgit.1
+++ b/dgit.1
@@ -338,8 +338,8 @@ which uses
 Set up the working tree's
 .B .git/info/attributes
 to disable all transforming attributes for all files.
-This is done by defining a macro attribute
-.B dgit-defuse-attrs
+This is done by defining a macro attribute,
+.B dgit-defuse-attrs,
 and applying it to
 .BR * .
 For why, see
@@ -355,7 +355,7 @@ in .git/info/attributes,
 but it is insufficient,
 because it was made by an earlier version of dgit
 and git has since introduced new transforming attributes,
-modifies the macro to disable the newer transformations.
+this modifies the macro to disable the newer transformations.
 
 (If there is already a macro attribute line
 .B [attr]dgit-defuse-attrs
@@ -448,7 +448,7 @@ and dgit actually imports the dsc
 dgit will make a pseudomerge
 so that the result is necessarily fast forward
 from the existing branch.
-Otherwise, if branch already exists,
+Otherwise, if \fIbranch\fR already exists,
 dgit will stop with an error message.
 
 If
@@ -538,6 +538,13 @@ 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.
+
+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
+it will just check that there are no untracked unignored files.
+See --clean=git[-ff],always, below.
 .TP
 .BR --clean=git-ff " | " -wgf
 Use
@@ -548,6 +555,10 @@ git clean -xdf
 but it also removes any subdirectories containing different git
 trees (which only unusual packages are likely to create).
 .TP
+.BR --clean=git "[" -ff "]" ,always " | " -wga " | " -wgfa
+Like --clean=git, but always does the clean and not just a check,
+deleting any untracked un-ignored files.
+.TP
 .BR --clean=check " | " --clean=check,ignores " | " -wc " | " -wci
 Merely check that the tree is clean (does not contain uncommitted
 files).
@@ -598,6 +609,25 @@ 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
@@ -745,7 +775,7 @@ The use of --deliberately is declared and published in the signed tags
 generated for you by dgit,
 so that the archive software can give effect to your intent,
 and
-for the benefit humans looking at the history.
+for the benefit of humans looking at the history.
 The meanings of
 .IR something s
 understood in the context of Debian are discussed below:
@@ -822,7 +852,7 @@ because the dgit git tree does not have a
 directory.)
 .TP
 .BR --quilt=nocheck " | " --no-quilt-fixup
-Do not check whether up source format `3.0 (quilt)' metadata needs
+Do not check whether 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
@@ -903,7 +933,7 @@ How to set this up is not yet documented.
 .TP
 .BI -C changesfile
 Specifies the .changes file which is to be uploaded.  By default
-dgit push looks for single .changes file in the parent directory whose
+dgit push looks for a single .changes file in the parent directory whose
 filename suggests it is for the right package and version.
 
 If the specified
@@ -1055,6 +1085,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 ,
@@ -1242,11 +1290,11 @@ One of the values for the command line --clean= option; used if
 .TP
 .BR dgit-distro. \fIdistro\fR .clean-mode-newer
 Like .clean-mode,
-but ignored if the value does not make sense to this version of dgit.
+but ignored if the value is unknown 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
@@ -1280,10 +1328,10 @@ used, respectively.  Only used if .setup-usermail is not disabled.
 .TP
 .BI dgit-distro. distro .setup-useremail
 Whether to set user.name and user.email in new git trees.
-True by default.  Ignored for dgit setup-setup-useremail, which does it anyway.
+True by default.  Ignored for dgit setup-useremail, which does it anyway.
 .TP
 .BI dgit-distro. distro .setup-mergechangelogs
-Whether to setup a merge driver which uses dpkg-mergechangelogs for
+Whether to set up a merge driver which uses dpkg-mergechangelogs for
 debian/changelog.  True by default.  Ignored for dgit
 setup-mergechangelogs, which does it anyway.
 .TP
@@ -1307,8 +1355,9 @@ Works like
 To pass several options, configure multiple values in git config
 (with git config --add).  The options for
 .BI dgit.default.opts- cmd
+and
 .BI dgit-distro. distro /push.opts- cmd
-and are all used, followed by options from dgit's command line.
+are all used, followed by options from dgit's command line.
 .SH ACCESS CONFIGURATION
 There are many other settings which specify how a particular distro's
 services (archive and git) are provided.  These should not normally be