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

diff --git a/dgit.1 b/dgit.1
index f0d637df..d23dde01 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,7 +146,7 @@ commit.
 
 Tagging, signing and actually uploading should be left to dgit push.
 
-dgit's build operations access the the network,
+dgit's build operations access the network,
 to get the -v option right.
 See -v, below.
 .TP
@@ -194,6 +198,35 @@ 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
@@ -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
@@ -389,7 +424,7 @@ If this is a problem
 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
 causes dgit to insist that the signature on the .dsc is valid
@@ -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
@@ -434,10 +469,30 @@ 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
+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
@@ -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,11 +555,26 @@ 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.
+
+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.
@@ -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
@@ -551,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.
@@ -628,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)
@@ -646,8 +759,12 @@ And it is only effective with
 --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
 Declare that you are deliberately doing
@@ -658,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:
@@ -735,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
@@ -816,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
@@ -832,7 +949,7 @@ default, in
 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
@@ -844,14 +961,20 @@ 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
+Specifies where to find and create tarballs, binary packages,
+source packages, .changes files, and so on.
+
+By default, dgit uses the parent directory
 .RB ( .. ).
 
-Also see the
+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 option
-(which this command line option overrides).
+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.
@@ -922,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 ,
@@ -960,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 ,
@@ -969,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 ,
@@ -1007,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
@@ -1135,6 +1288,12 @@ the default value used if there is no distro-specific setting.
 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.
@@ -1169,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
@@ -1196,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
@@ -1282,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