TODO.BRANCH: Add a todo list item

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index 60e6a25d6bbfdbdd7b64d966fc9dec8ca52358c1..87ad0fce4b8f589f38ec85d378567d632cf9ffca 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -126,18 +126,17 @@ Print a usage summary.
 Constructs the source package, uses
 .B  sbuild
 to do a binary build, and uses mergechanges to merge the source and
 Constructs the source package, uses
 .B  sbuild
 to do a binary build, and uses mergechanges to merge the source and

-binary changes files.  Options and argumments after sbuild will be
-passed on to sbuild.  Changes files matching
-.IB package _ version _*.changes
-in the parent directory will be removed; the output is left in
+binary changes files.  Options and arguments after sbuild will be
+passed on to sbuild.
+The output is left in

 .IR package \fB_\fR version \fB_multi.changes\fR.
 
 Tagging, signing and actually uploading should be left to dgit push.
 .TP
 .IR package \fB_\fR version \fB_multi.changes\fR.
 
 Tagging, signing and actually uploading should be left to dgit push.
 .TP

-\fBdgit git-build\fR ...
+\fBdgit gbp-build\fR ...

 Runs
 .B git-buildpackage
 Runs
 .B git-buildpackage

-with some suitable options.  Options and argumments after git-build
+with some suitable options.  Options and arguments after gbp-build

 will be passed on to git-buildpackage.
 
 Tagging, signing and actually uploading should be left to dgit push.
 will be passed on to git-buildpackage.
 
 Tagging, signing and actually uploading should be left to dgit push.


@@ -198,13 +197,27 @@ You will need similar enough versions of dgit on the build-host and
 the invocation host.  The build-host needs gnupg installed, with your
 public key in its keyring (but not your private key, obviously).
 .TP
 the invocation host.  The build-host needs gnupg installed, with your
 public key in its keyring (but not your private key, obviously).
 .TP

+.B dgit setup-new-tree
+Configure the current working tree the way that dgit clone would have
+set it up.  Like running
+.B dgit setup-useremail
+and
+.B setup-mergechangelogs
+(but only does each thing if dgit is configured to do it automatically).
+You can use these in any git repository, not just ones used with
+the other dgit operations.
+.TP
+.B dgit setup-useremail
+Set the working tree's user.name and user.email from the
+distro-specific dgit configuration
+.RB ( dgit-distro. \fIdistro\fR .user-name " and " .user-email ),
+or DEBFULLNAME or DEBEMAIL.
+.TP

 .B dgit setup-mergechangelogs
 Configures a git merge helper for the file
 .B debian/changelog
 which uses
 .BR dpkg-mergechangelogs .
 .B dgit setup-mergechangelogs
 Configures a git merge helper for the file
 .B debian/changelog
 which uses
 .BR dpkg-mergechangelogs .

-You can use this in any git repository, not just ones used with
-the other dgit operations.

 .TP
 .B dgit quilt-fixup
 `3.0 (quilt)' format source packages need changes representing not
 .TP
 .B dgit quilt-fixup
 `3.0 (quilt)' format source packages need changes representing not


@@ -246,8 +259,8 @@ Use
 for signing the tag and the upload.  The default comes from the
 distro's
 .B keyid
 for signing the tag and the upload.  The default comes from the
 distro's
 .B keyid

-config setting (see CONFIGURATION, below), or failing that, gnupg's
-default.
+config setting (see CONFIGURATION, below), or failing that, the
+uploader trailer line in debian/changelog.

 .TP
 .BR --no-sign
 does not sign tags or uploads (meaningful only with push).
 .TP
 .BR --no-sign
 does not sign tags or uploads (meaningful only with push).


@@ -306,8 +319,10 @@ The build-dependencies are not checked (due to
 which violates policy, but may work in practice.
 .TP
 .BR -N " | " --new
 which violates policy, but may work in practice.
 .TP
 .BR -N " | " --new

-The package may be new in this suite.  Without this, dgit will
-refuse to push.
+The package is or may be new in this suite.  Without this, dgit will
+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.
 .TP
 .BR --ignore-dirty
 Do not complain if the working tree does not match your git HEAD.


@@ -374,7 +389,7 @@ fixing up, dgit push will fail.
 .TP
 .BI -D
 Prints debugging information to stderr.  Repeating the option produces
 .TP
 .BI -D
 Prints debugging information to stderr.  Repeating the option produces

-more output (currently, up to -DDD is meaningfully different).
+more output (currently, up to -DDDD is meaningfully different).

 .TP
 .BI -c name = value
 Specifies a git configuration option, to be used for this run.
 .TP
 .BI -c name = value
 Specifies a git configuration option, to be used for this run.


@@ -414,6 +429,7 @@ Specifies alternative programs to use instead of
 .BR gpg ,
 .BR ssh ,
 .BR dgit ,
 .BR gpg ,
 .BR ssh ,
 .BR dgit ,

+.BR git ,

 or
 .BR mergechanges .
 
 or
 .BR mergechanges .
 


@@ -460,6 +476,10 @@ this applies only when the program is invoked directly by dgit.
 Usually, for passing options to dpkg-genchanges, you should use
 .BR --ch: \fIoption\fR.
 
 Usually, for passing options to dpkg-genchanges, you should use
 .BR --ch: \fIoption\fR.
 

+Specifying --git 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 above regarding ssh and dgit.
 
 NB that --gpg:option is not supported (because debsign does not
 See notes above regarding ssh and dgit.
 
 NB that --gpg:option is not supported (because debsign does not


@@ -493,8 +513,7 @@ How to set this up is not yet documented.
 .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
 .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

-filename suggests it is for the right package and version - or,
-if there is a _multi.changes file, dgit uses that.
+filename suggests it is for the right package and version.

 
 If the specified
 .I changesfile
 
 If the specified
 .I changesfile


@@ -505,6 +524,18 @@ otherwise, the changes file is expected in that directory (by
 default, in
 .BR .. ).
 .TP
 default, in
 .BR .. ).
 .TP

+.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
+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
+.B \-\-no-rm-old-changes
+can be used to override a previous \-\-rm-old-changes
+or the .rm-old-changes configuration setting.
+.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 the built files to be uploaded.
 By default, dgit looks in the parent directory


@@ -589,7 +620,7 @@ tracking branch.  Then somehow, using your other git history
 plus appropriate diffs and cherry picks from the dgit remote tracking
 branch, construct a git commit whose tree corresponds to the tree to use for the
 next upload.  If that commit-to-be-uploaded is not a descendant of the
 plus appropriate diffs and cherry picks from the dgit remote tracking
 branch, construct a git commit whose tree corresponds to the tree to use for the
 next upload.  If that commit-to-be-uploaded is not a descendant of the

-dig remote tracking branch, check it out and say
+dgit remote tracking branch, check it out and say

 .BR "git merge -s ours remotes/dgit/dgit/" \fIsuite\fR;
 that tells git that we are deliberately throwing away any differences
 between what's in the archive and what you intend to upload.
 .BR "git merge -s ours remotes/dgit/dgit/" \fIsuite\fR;
 that tells git that we are deliberately throwing away any differences
 between what's in the archive and what you intend to upload.


@@ -613,6 +644,23 @@ which is involved.  The config used is thereafter that for the distro.
 .BI dgit.default.distro " distro"
 The default distro for an unknown suite.
 .TP
 .BI dgit.default.distro " distro"
 The default distro for an unknown suite.
 .TP

+.BR dgit.default. *
+for each
+.BR dgit-distro. \fIdistro\fR . *,
+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.
+.TP
+.BR dgit-distro. \fIdistro\fR .quilt-mode
+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
+is specified.  The default is not to remove.
+.TP

 .BR dgit-distro. \fIdistro\fR .readonly " " auto | a " | " true | t | y | 1 " | " false | f | n | 0
 Whether you have push access to the distro.
 For Debian, it is OK to use auto, which uses readonly mode if you are
 .BR dgit-distro. \fIdistro\fR .readonly " " auto | a " | " true | t | y | 1 " | " false | f | n | 0
 Whether you have push access to the distro.
 For Debian, it is OK to use auto, which uses readonly mode if you are


@@ -631,6 +679,37 @@ Not relevant for Debian.
 .TP
 .BI dgit-distro. distro .upload-host
 Might be useful if you have an intermediate queue server.
 .TP
 .BI dgit-distro. distro .upload-host
 Might be useful if you have an intermediate queue server.

+.TP
+.BI dgit-distro. distro .user-name " " dgit-distro. distro .user-email
+Values to configure for user.name and user.email in new git trees.  If
+not specified, the DEBFULLNAME and DEBEMAIL environment variables are
+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.
+.TP
+.BI dgit-distro. distro .setup-mergechangelogs
+Whether to setup a merge driver which uses dpkg-mergechangelogs for
+debian/changelog.  True by default.  Ignored for dgit
+setup-mergechangelogs, which does it anyway.
+.TP
+.BI dgit-distro. distro .cmd- cmd
+Program to use instead of
+.IR cmd .
+Works like
+.BR -- \fIcmd\fR = "... ."
+.TP
+.BI dgit-distro. distro .opts- cmd
+Extra options to pass to
+.IR cmd .
+Works like
+.BR -- \fIcmd\fR : "... ."
+To pass several options, configure multiple values in git config
+(with git config --add).  The options for
+.BI dgit.default.opts- cmd
+.BI dgit-distro. distro /push.opts- cmd
+and 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
 .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


@@ -667,6 +746,8 @@ or when pushing and
 .TP
 .BI dgit-distro. distro .archive-query-default-component
 .TP
 .TP
 .BI dgit-distro. distro .archive-query-default-component
 .TP

+.BI dgit-distro. distro .dgit-tag-format
+.TP

 .BI dgit-distro. distro .ssh
 .TP
 .BI dgit-distro. distro .sshpsql-dbname
 .BI dgit-distro. distro .ssh
 .TP
 .BI dgit-distro. distro .sshpsql-dbname


@@ -674,10 +755,6 @@ or when pushing and
 .BR dgit-distro. \fIdistro\fR . ( git | sshpsql ) - ( user | host | user-force )
 .TP
 .BI dgit-distro. distro .backports-quirk
 .BR dgit-distro. \fIdistro\fR . ( git | sshpsql ) - ( user | host | user-force )
 .TP
 .BI dgit-distro. distro .backports-quirk

-.TP
-.BR dgit.default. *
-for each
-.BR dgit-distro. \fIdistro\fR . *

 .SH ENVIRONMENT VARIABLES
 .TP
 .BR DGIT_SSH ", " GIT_SSH
 .SH ENVIRONMENT VARIABLES
 .TP
 .BR DGIT_SSH ", " GIT_SSH


@@ -689,6 +766,10 @@ interprets it the same way as git does.
 See
 also the --ssh= and --ssh: options.
 .TP
 See
 also the --ssh= and --ssh: options.
 .TP

+.BR DEBEMAIL ", " DEBFULLNAME
+Default git user.email and user.name for new trees.  See
+.BR "dgit setup-new-tree" .
+.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
 .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


@@ -724,8 +805,6 @@ There should be an option which arranges for the `3.0 (quilt)'
 autocommit(s) to not appear on your HEAD, but instead only in the
 remote tracking suite branch.
 
 autocommit(s) to not appear on your HEAD, but instead only in the
 remote tracking suite branch.
 

-The option parser requires values to be cuddled to the option name.
-

 --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.
 --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.


@@ -738,4 +817,4 @@ non-dry-run dgit fetch first will help.
 \fBgit-buildpackage\fP(1),
 \fBdpkg-buildpackage\fP(1),
 .br
 \fBgit-buildpackage\fP(1),
 \fBdpkg-buildpackage\fP(1),
 .br

-https://wiki.debian.org/Alioth
+https://browse.dgit.debian.org/