X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=682562cab85b56fb7ee45215d89de3e39b13bc3c;hp=1460938a4e5f329be38385b287b9683b01f12671;hb=3193ca2bad512d2563797eca11ceb9d707a65004;hpb=177768519130da7d21705598f2b5d961cf408a4b

diff --git a/dgit.1 b/dgit.1
index 1460938a..682562ca 100644
--- a/dgit.1
+++ b/dgit.1
@@ -17,6 +17,10 @@ dgit \- git integration with the Debian archive
 [\fIbuild\-opts\fP]
 .br
 .B dgit
+[\fIdgit\-opts\fP] \fBpbuilder\fP|\fBcowbuilder\fP
+[\fIdebbuildopts\fP]
+.br
+.B dgit
 [\fIdgit\-opts\fP] \fBpush\fP|\fBpush-source\fP [\fIdgit\-opts\fP]
 [\fIsuite\fP]
 .br
@@ -126,7 +130,7 @@ If you already have the suite branch,
 and want to merge your branch with updates from the archive,
 use dgit pull.
 
-dgit checkout will normally need to aceess the archive server,
+dgit checkout will normally need to access the archive server,
 to canonicalise the provided suite name.
 The exception is if you specify the canonical name,
 and the branch (or tracking branch) already exists.
@@ -142,9 +146,9 @@ commit.
 
 Tagging, signing and actually uploading should be left to dgit push.
 
-dgit's build operations access the the network,
-to get the -v option right.
-See -v, below.
+dgit's build operations access the network,
+to get the \-v option right.
+See \-v, below.
 .TP
 \fBdgit build-source\fR ...
 Builds the source package, and a changes file for a prospective
@@ -159,12 +163,12 @@ Tagging, signing and actually uploading should be left to dgit
 push-source, or dgit push.
 .TP
 .B dgit clean
-Cleans the current working tree (according to the --clean= option in
+Cleans the current working tree (according to the \-\-clean= option in
 force).
 .TP
-\fBdgit update-vcs-git\fR [\fIsuite\fP|\fB.\fR] [\fB--\fR] [\fIgit fetch options\fR]
+\fBdgit update-vcs-git\fR [\fIsuite\fP|\fB.\fR] [\fB\-\-\fR] [\fIgit fetch options\fR]
 .TQ
-\fBdgit update-vcs-git\fR [\fIsuite|\fP\fB.\fR] \fB-\fR
+\fBdgit update-vcs-git\fR [\fIsuite|\fP\fB.\fR] \fB\-\fR
 Sets up, or updates the url of, the vcs-git remote, and
 (unless \fB-\fR was specified)
 runs git fetch on it.
@@ -190,10 +194,39 @@ The output is left in
 .IP
 Note that by default
 sbuild does not build arch-independent packages.
-You probably want to pass -A, to request those.
+You probably want to pass \-A, to request those.
 .IP
 Tagging, signing and actually uploading should be left to dgit push.
 .TP
+\fBdgit pbuilder\fR [\fIdebbuildopts\fP]
+Constructs the source package, uses
+.B  pbuilder
+to do a binary build, and uses mergechanges to merge the source and
+binary changes files.
+The output is left in
+.IR package \fB_\fR version \fB_multi.changes\fR.
+
+You should ensure that your dgit \-\-build-products-dir setting matches
+your pbuilder \-\-buildresult.
+
+The \fIdebbuildopts\fP are passed to pbuilder using its \-\-debbuildopts
+option.  If you want to pass other options to pbuilder, use the
+\fB\-\-pbuilder:\fR dgit option as described below
+(remember that dgit options should appear between \fBdgit\fR and
+\fBpbuilder\fR).
+
+You should ensure that in your pbuilderrc you do
+.B not
+have the setting
+.B SOURCE_ONLY_CHANGES=yes
+as this may cause trouble.
+.TP
+\fBdgit cowbuilder\fR [\fIdebbuildopts\fP]
+Like \fBdgit pbuilder\fR, but uses
+.B cowbuilder
+instead of
+.B pbuilder.
+.TP
 \fBdgit gbp-build\fR ...
 Runs
 .B git-buildpackage
@@ -218,7 +251,7 @@ In more detail: dgit push checks that the current HEAD corresponds to
 the .dsc.  It then pushes the HEAD to the suite's dgit-repos branch,
 adjusts the .changes to include any .origs which the archive lacks
 and exclude .origs which the archive has
-(so -sa and -sd are not needed when building for dgit push),
+(so \-sa and \-sd are not needed when building for dgit push),
 makes a signed git tag, edits the .dsc to contain the dgit metadata
 field, runs debsign to sign the upload (.dsc and .changes), pushes the
 signed tag, and finally uses dput to upload the .changes to the
@@ -234,11 +267,11 @@ to prepare the branch
 for source package upload and push.
 .TP
 \fBdgit push-source\fR [\fIsuite\fP]
-Without \fB-C\fR, builds a source package and dgit pushes it.  Saying
+Without \fB\-C\fR, builds a source package and dgit pushes it.  Saying
 \fBdgit push-source\fR is like saying "update the source code in the
 archive to match my git HEAD, and let the autobuilders do the rest."
 
-With \fB-C\fR, performs a dgit push, additionally ensuring that no
+With \fB\-C\fR, performs a dgit push, additionally ensuring that no
 binary packages are uploaded.
 .TP
 \fBdgit rpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR [\fIpush args...\fR]
@@ -253,7 +286,7 @@ l l.
 1.	Clone on build host (dgit clone)
 2.	Edit code on build host (edit, git commit)
 3.	Build package on build host (dgit build)
-4.	Test package on build host or elsewhere (dpkg -i, test)
+4.	Test package on build host or elsewhere (dpkg \-i, test)
 5.	Upload by invoking dgit rpush on host with your GPG key.
 .TE
 
@@ -305,14 +338,16 @@ 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
 .B GITATTRIBUTES
 in
 .BR dgit(7) .
+Note that only attributes affecting the working tree are suppressed.
+git-archive may remain exciting.
 
 If there is an existing macro attribute line
 .B [attr]dgit-defuse-attrs
@@ -320,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
@@ -355,7 +390,7 @@ dgit can make patches in some situations where git-debrebase fails,
 so dgit quilt-fixup can be useful in its own right.
 To always use dgit's own patch generator
 instead of git-debrebase make-patches,
-pass --git-debrebase=true to dgit.
+pass \-\-git-debrebase=true to dgit.
 
 See
 .B FORMAT 3.0 (QUILT)
@@ -386,14 +421,14 @@ and specifying where to find that commit
 import-dsc might need online access.
 If this is a problem
 (or dgit's efforts to find the commit fail),
-consider --no-chase-dsc-distro
-or --force-import-dsc-with-dgit-field.
+consider \-\-no-chase-dsc-distro
+or \-\-force-import-dsc-with-dgit-field.
 
-There is only only sub-option:
+There is only one sub-option:
 
-.B --require-valid-signature
+.B \-\-require-valid-signature
 causes dgit to insist that the signature on the .dsc is valid
-(using the same criteria as dpkg-source -x).
+(using the same criteria as dpkg-source \-x).
 Otherwise, dgit tries to verify the signature but
 the outcome is reported only as messages to stderr.
 
@@ -401,7 +436,7 @@ If
 .I branch
 is prefixed with
 .B +
-then if it already exists, it will be simply ovewritten,
+then if it already exists, it will be simply overwritten,
 no matter its existing contents.
 If
 .I branch
@@ -413,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
@@ -433,25 +468,45 @@ This is hopefully suitable for use as a git remote url.
 It may not be useable in a browser.
 .TP
 .BI "dgit print-dpkg-source-ignores"
-Prints the -i and -I arguments which must be passed to dpkg-souce
-to cause it to exclude exactly the .git diredcory
+Prints the \-i and \-I arguments which must be passed to dpkg-souce
+to cause it to exclude exactly the .git directory
 and nothing else.
 The separate arguments are unquoted, separated by spaces,
 and do not contain spaces.
+.TP
+.B dgit print-unapplied-treeish
+Constructs a tree-ish approximating the patches-unapplied state
+of your 3.0 (quilt) package,
+and prints the git object name to stdout.
+This requires appropriate .orig tarballs.
+This tree object is identical to your .origs
+as regards upstream files.
+The contents of the debian subdirectory is not interesting
+and should not be inspected;
+except that debian/patches will be identical to your HEAD.
+
+To make this operate off-line,
+the access configuration key
+which is used to determine the build-products-dir
+is the uncanonicalised version of the suite name from the changelog,
+or (of course) dgit.default.build-products-dir.
+See ACCESS CONFIGURATION, below.
+
+This function is primarily provided for the benefit of git-debrebase.
 .SH OPTIONS
 .TP
-.BR --dry-run " | " -n
+.BR \-\-dry-run " | " \-n
 Go through the motions, fetching all information needed, but do not
 actually update the output(s).  For push, dgit does
 the required checks and leaves the new .dsc in a temporary file,
 but does not sign, tag, push or upload.
 .TP
-.BR --damp-run " | " -L
+.BR \-\-damp-run " | " \-L
 Go through many more of the motions: do everything that doesn't
 involve either signing things, or making changes on the public
 servers.
 .TP
-.BI -k keyid
+.BI \-k keyid
 Use
 .I keyid
 for signing the tag and the upload.  The default comes from the
@@ -483,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
@@ -493,13 +555,28 @@ 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=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).
 Avoids running rules clean,
 and can avoid needing the build-dependencies.
-.TP
-.BR --clean=none " | " -wn
+
+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.
 Avoids running rules clean,
 and can avoid needing the build-dependencies.
@@ -507,21 +584,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
@@ -529,12 +635,17 @@ refuse to push.  It may (for Debian, will) be unable to access the git
 history for any packages which have been newly pushed and have not yet
 been published.
 .TP
-.BR --ignore-dirty
-Do not complain if the working tree does not match your git HEAD.
+.BR --include-dirty
+Do not complain if the working tree does not match your git HEAD,
+and when building,
+include the changes from your working tree.
 This can be useful with build, if you plan to commit later.  (dgit
 push will still ensure that the .dsc you upload and the git tree
 you push are identical, so this option won't make broken pushes.)
 .TP
+.BR --ignore-dirty
+Deprecated alias for --include-dirty.
+.TP
 .BR --overwrite [=\fIprevious-version\fR]
 Declare that your HEAD really does contain
 all the (wanted) changes
@@ -546,6 +657,13 @@ your git branch is not a descendant
 of the version in the archive
 according to the git revision history.
 
+It is safer not to specify
+.IR previous-version ,
+and usually it's not needed.
+Just say
+.BR \-\-overwrite ,
+unless you know what you are doing.
+
 This option is useful if you are the maintainer, and you have
 incorporated NMU changes into your own git workflow in a way that
 doesn't make your branch a fast forward from the NMU.
@@ -581,7 +699,7 @@ git history, so that your push is a fast forward from the archive.
 implying a split between the dgit view and the
 maintainer view, the pseudo-merge will appear only in the dgit view.)
 .TP
-.BR --delayed =\fIdays\fR
+.BR \-\-delayed =\fIdays\fR
 Upload to a DELAYED queue.
 
 .B WARNING:
@@ -623,7 +741,7 @@ Also,
 it can mean that
 dgit fails to find necessary git commits.
 .TP
-.BR --dgit-view-save= \fIbranch\fR|\fIref\fR
+.BR \-\-save-dgit-view= \fIbranch\fR|\fIref\fR
 Specifies that when a split view quilt mode is in operation,
 and dgit calculates
 (or looks up in its cache)
@@ -636,24 +754,28 @@ so don't specify a branch you want to keep.
 This option is effective only with the following operations:
 quilt-fixup; push; all builds.
 And it is only effective with
---[quilt=]gbp,
---[quilt=]dpm,
---quilt=unpatched.
+\-\-[quilt=]gbp,
+\-\-[quilt=]dpm,
+\-\-quilt=unpatched.
 
 If ref does not start with refs/
-it is taken to to be a branch -
+it is taken to be a branch -
 i.e. refs/heads/ is prepended.
+
+.B \-\-dgit-view-save
+is a deprecated alias for
+\-\-save-dgit-view.
 .TP
-.BI --deliberately- something
+.BI \-\-deliberately- something
 Declare that you are deliberately doing
 .IR something .
 This can be used to override safety catches, including safety catches
 which relate to distro-specific policies.
-The use of --deliberately is declared and published in the signed tags
+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:
@@ -730,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
@@ -780,16 +902,16 @@ for the dgit view.
 dgit quilt-fixup will merely do some checks,
 and cache the maintainer view.
 
-.B If you have a branch like this it is essential to specify the appropriate --quilt= option!
+.B If you have a branch like this it is essential to specify the appropriate \-\-quilt= option!
 This is because it is not always possible to tell: a patches-unapplied
 git branch of a package with one patch, for example, looks very like
 a patches-applied branch where the user has used git revert to
 undo the patch, expecting to actually revert it.
 However, if you fail to specify the right \-\-quilt option,
 and you aren't too lucky, dgit will notice the problem and stop,
-with a useful hint. 
+with a useful hint.
 .TP
-.BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
+.BR \-d "\fIdistro\fR | " \-\-distro= \fIdistro\fR
 Specifies that the suite to be operated on is part of distro
 .IR distro .
 This overrides the default value found from the git config option
@@ -801,7 +923,7 @@ for accessing the archive and dgit-repos) used are
 If your suite is part of a distro that dgit already knows about, you
 can use this option to make dgit work even if your dgit doesn't know
 about the suite.  For example, specifying
-.B -ddebian
+.B \-ddebian
 will work when the suite is an unknown suite in the Debian archive.
 
 To define a new distro it is necessary to define methods and URLs
@@ -809,25 +931,25 @@ for fetching (and, for dgit push, altering) a variety of information both
 in the archive and in dgit-repos.
 How to set this up is not yet documented.
 .TP
-.BI -C changesfile
+.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
 .I changesfile
 pathname contains slashes, the directory part is also used as
 the value for
-.BR --build-products-dir ;
+.BR \-\-build-products-dir ;
 otherwise, the changes file is expected in that directory (by
 default, in
 .BR .. ).
 .TP
-.B --rm-old-changes
+.B \-\-rm-old-changes
 When doing a build, delete any changes files matching
 .IB package _ version _*.changes
 before starting.  This ensures that
-dgit push (and dgit sbuild) will be able to unambigously
+dgit push (and dgit sbuild) will be able to unambiguously
 identify the relevant changes files from the most recent build, even
 if there have been previous builds with different tools or options.
 The default is not to remove, but
@@ -838,10 +960,21 @@ or the .rm-old-changes configuration setting.
 Note that \fBdgit push-source\fR will always find the right .changes,
 regardless of this option.
 .TP
-.BI --build-products-dir= directory
-Specifies where to find the built files to be uploaded.
-By default, dgit looks in the parent directory
+.BI \-\-build-products-dir= directory
+Specifies where to find and create tarballs, binary packages,
+source packages, .changes files, and so on.
+
+By default, dgit uses the parent directory
 .RB ( .. ).
+
+Changing this setting may necessitate
+moving .orig tarballs to the new directory,
+so it is probably best to
+use the
+.BI dgit.default.build-products-dir
+configuration setting
+(see CONFIGURATION, below)
+which this command line option overrides).
 .TP
 .BI --no-rm-on-error
 Do not delete the destination directory if clone fails.
@@ -912,6 +1045,8 @@ Specifies a single additional option to pass to
 .BR dpkg-buildpackage ,
 .BR dpkg-genchanges ,
 .BR sbuild ,
+.BR pbuilder ,
+.BR cowbuilder ,
 .BR ssh ,
 .BR dgit ,
 .BR git-debrebase ,
@@ -934,23 +1069,41 @@ and cause lossage.
 For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild,
 the option applies only when the program is invoked directly by dgit.
 Usually, for passing options to dpkg-genchanges, you should use
-.BR --ch: \fIoption\fR.
+.BR \-\-ch: \fIoption\fR.
 
-Specifying --git is not effective for some lower-level read-only git
+Specifying \-\-git is not effective for some lower-level read-only git
 operations performed by dgit, and also not when git is invoked by
 another program run by dgit.
 
 See notes below regarding ssh and dgit.
 
-NB that --gpg:option is not supported (because debsign does not
+NB that \-\-gpg:option is not supported (because debsign does not
 have that facility).
 But see
-.B -k
+.B \-k
 and the
 .B keyid
 distro config setting.
 .TP
-.RI \fB--curl=\fR program " | \fB--dput=\fR" program  " |..."
+.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 ,
 .BR dput ,
@@ -959,6 +1112,8 @@ Specifies alternative programs to use instead of
 .BR dpkg-buildpackage ,
 .BR dpkg-genchanges ,
 .BR sbuild ,
+.BR pbuilder ,
+.BR cowbuilder ,
 .BR gpg ,
 .BR ssh ,
 .BR dgit ,
@@ -983,8 +1138,8 @@ For
 .BR dgit ,
 specifies the command to run on the remote host when dgit
 rpush needs to invoke a remote copy of itself.  (dgit also reinvokes
-itself as the EDITOR for dpkg-source --commit; this is done using
-argv[0], and is not affected by --dgit=).
+itself as the EDITOR for dpkg-source \-\-commit; this is done using
+argv[0], and is not affected by \-\-dgit=).
 
 .BR gbp-build 's
 value
@@ -997,6 +1152,14 @@ In both cases,
 unusually, the specified value is split on whitespace
 to produce a command and possibly some options and/or arguments.
 
+For pbuilder and cowbuilder, the defaults are
+.BR "sudo -E pbuilder"
+and
+.BR "sudo -E cowbuilder"
+respectively.
+Like with gbp-build and gbp pq,
+the specified value is split on whitespace.
+
 For
 .BR ssh ,
 the default value is taken from the
@@ -1009,25 +1172,25 @@ git config variables
 .BI dgit-distro. distro .ssh
 and
 .B .dgit.default.ssh
-(which can in turn be overridden with -c).  Also, when dgit is using
+(which can in turn be overridden with \-c).  Also, when dgit is using
 git to access dgit-repos, only git's idea of what ssh to use (eg,
 .BR GIT_SSH )
 is relevant.
 .TP
-.BI --existing-package= package
+.BI \-\-existing-package= package
 dgit push needs to canonicalise the suite name.  Sometimes, dgit
 lacks a way to ask the archive to do this without knowing the
-name of an existing package.  Without --new we can just use the
-package we are trying to push.  But with --new that will not work, so
+name of an existing package.  Without \-\-new we can just use the
+package we are trying to push.  But with \-\-new that will not work, so
 we guess
 .B dpkg
 or use the value of this option.  This option is not needed with the
 default mechanisms for accessing the archive.
 .TP
-.BR -h | --help
+.BR \-h | \-\-help
 Print a usage summary.
 .TP
-.BI --initiator-tempdir= directory
+.BI \-\-initiator-tempdir= directory
 dgit rpush uses a temporary directory on the invoking (signing) host.
 This option causes dgit to use
 .I directory
@@ -1036,7 +1199,7 @@ removed and recreated before dgit starts, rather than removed
 after dgit finishes.  The directory specified must be an absolute
 pathname.
 .TP
-.BI --force- something
+.BI \-\-force- something
 Instructs dgit to try to proceed despite detecting
 what it thinks is going to be a fatal problem.
 .B This is probably not going to work.
@@ -1044,45 +1207,45 @@ These options are provided as an escape hatch,
 in case dgit is confused.
 (They might also be useful for testing error cases.)
 .TP
-.B --force-import-dsc-with-dgit-field
+.B \-\-force-import-dsc-with-dgit-field
 Tell dgit import-dsc to treat a .dsc with a Dgit field
 like one without it.
 The result is a fresh import,
 discarding the git history
 that the person who pushed that .dsc was working with.
 .TP
-.B --force-uploading-binaries
+.B \-\-force-uploading-binaries
 Carry on and
 upload binaries
 even though dgit thinks your distro does not permit that.
 .TP
-.B --force-uploading-source-only
+.B \-\-force-uploading-source-only
 Carry on and do a source-only upload,
 without any binaries,
 even though dgit thinks your distro does not permit that,
 or does not permit that in this situation.
 .TP
-.B --force-unrepresentable
+.B \-\-force-unrepresentable
 Carry on even if
 dgit thinks that your git tree contains changes
 (relative to your .orig tarballs)
 which dpkg-source is not able to represent.
 Your build or push will probably fail later.
 .TP
-.B --force-changes-origs-exactly
+.B \-\-force-changes-origs-exactly
 Use the set of .origs specified in your .changes, exactly,
 without regard to what is in the archive already.
 The archive may well reject your upload.
 .TP
-.B --force-unsupported-source-format
+.B \-\-force-unsupported-source-format
 Carry on despite dgit not understanding your source package format.
 dgit will probably mishandle it.
 .TP
-.B --force-dsc-changes-mismatch
+.B \-\-force-dsc-changes-mismatch
 Do not check whether .dsc and .changes match.
 The archive will probably reject your upload.
 .TP
-.BR --force-import-gitapply-absurd " | " --force-import-gitapply-no-absurd
+.BR \-\-force-import-gitapply-absurd " | " \-\-force-import-gitapply-no-absurd
 Force on or off the use of the absurd git-apply emulation
 when running gbp pq import
 when importing a package from a .dsc.
@@ -1096,6 +1259,12 @@ on the dgit command line.
 .LP
 Settings likely to be useful for an end user include:
 .TP
+.BI dgit.default.build-products-dir
+Specifies where to find the built files to be uploaded,
+when --build-products-dir is not specified.  The default is
+the parent directory
+.RB ( .. ).
+.TP
 .BR dgit-suite. \fIsuite\fR .distro " \fIdistro\fR"
 Specifies the distro for a suite.  dgit keys off the suite name (which
 appears in changelogs etc.), and uses that to determine the distro
@@ -1116,12 +1285,18 @@ for each
 the default value used if there is no distro-specific setting.
 .TP
 .BR dgit-distro. \fIdistro\fR .clean-mode
-One of the values for the command line --clean= option; used if
---clean is not specified.
+One of the values for the command line \-\-clean= option; used if
+\-\-clean is not specified.
+.TP
+.BR dgit-distro. \fIdistro\fR .clean-mode-newer
+Like .clean-mode,
+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-mode
-One of the values for the command line --quilt= option; used if
---quilt is not specified.
+One of the values for the command line \-\-quilt= option; used if
+\-\-quilt is not specified.
 .TP
 .BR dgit-distro. \fIdistro\fR .rm-old-changes
 Boolean, used if neither \-\-rm-old-changes nor \-\-no-rm-old-changes
@@ -1136,7 +1311,7 @@ git repository server.
 .TP
 .BI dgit-distro. distro .keyid
 See also
-.BR -k .
+.BR \-k .
 .TP
 .BI dgit-distro. distro .mirror " url"
 .TP
@@ -1153,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
@@ -1170,18 +1345,19 @@ True by default.  Ignored for dgit setup-gitattributes, which does it anyway.
 Program to use instead of
 .IR cmd .
 Works like
-.BR -- \fIcmd\fR = "... ."
+.BR \-\- \fIcmd\fR = "... ."
 .TP
 .BI dgit-distro. distro .opts- cmd
 Extra options to pass to
 .IR cmd .
 Works like
-.BR -- \fIcmd\fR : "... ."
+.BR \-\- \fIcmd\fR : "... ."
 To pass several options, configure multiple values in git config
-(with git config --add).  The options for
+(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
@@ -1258,7 +1434,7 @@ if it contains any whitespace will be passed to the shell.  GIT_SSH
 specifies just the program; no arguments can be specified, so dgit
 interprets it the same way as git does.
 See
-also the --ssh= and --ssh: options.
+also the \-\-ssh= and \-\-ssh: options.
 .TP
 .BR DEBEMAIL ", " DEBFULLNAME
 Default git user.email and user.name for new trees.  See
@@ -1266,7 +1442,7 @@ Default git user.email and user.name for new trees.  See
 .TP
 .BR gpg ", " dpkg- "..., " debsign ", " git ", " curl ", " dput ", " LWP::UserAgent
 and other subprograms and modules used by dgit are affected by various
-environment variables.  Consult the documentaton for those programs
+environment variables.  Consult the documentation for those programs
 for details.
 .SH BUGS
 There should be
@@ -1287,10 +1463,10 @@ your current HEAD.  Sadly this is necessary for packages in the `3.0
 (quilt)' source format.  This is ultimately due to what I consider
 design problems in quilt and dpkg-source.
 
---dry-run does not always work properly, as not doing some of the git
+\-\-dry-run does not always work properly, as not doing some of the git
 fetches may result in subsequent actions being different.  Doing a
 non-dry-run dgit fetch first will help.
---damp-run is likely to work much better.
+\-\-damp-run is likely to work much better.
 .SH SEE ALSO
 \fBdgit\fP(7),
 \fBdgit-*\fP(7),