.SH SYNOPSIS
.B dgit
[\fIdgit\-opts\fP] \fBclone\fP [\fIdgit\-opts\fP]
-\fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir]
+\fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
.br
.B dgit
[\fIdgit\-opts\fP] \fBfetch\fP|\fBpull\fP [\fIdgit\-opts\fP]
[\fIsuite\fP]
.br
.B dgit
-[\fIdgit\-opts\fP] \fBbuild\fP
-[\fIgit\-buildpackage\-opts\fP|\fIdpkg\-buildpackage\-opts\fp]
+[\fIdgit\-opts\fP] \fBbuild\fP|\fBsbuild\fP|\fBbuild-source\fP
+[\fIbuild\-opts\fp]
.br
.B dgit
[\fIdgit\-opts\fP] \fBpush\fP [\fIdgit\-opts\fP]
[\fIsuite\fP]
+.br
+.B dgit
+[\fIdgit\-opts\fP] \fIaction\fR ...
.SH DESCRIPTION
.B dgit
treats the Debian archive as a version control system, and
.B dgit-repos
which lives outside the Debian archive (currently, on Alioth).
-.B dgit clone
-and
-.B dgit fetch
-consult the archive and dgit-repos and fetch and/or construct the
-git view of the history. With clone, the destination directory (by
-default, the package name in the current directory) will be created,
-and the new directory's `origin' remote will be set up to point to
-the package's dgit-repos tree.
-
-.B dgit build
-runs
+The usual workflow is: 1. clone or fetch; 2. make and commit changes
+in git as desired; 3. run dgit build, dgit sbuild or dgit
+build-source, or generate the source and binary packages for upload
+some other way; 4. do pre-upload tests of the proposed upload; 5. run
+dgit push.
+.TP
+\fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
+Consults the archive and dgit-repos to construct the git view of
+history for
+.I package
+in
+.I suite
+.RB ( sid
+by default)
+in a new directory (named
+.BI ./ package
+by default);
+also, downloads any necessary orig tarballs.
+
+The suite's git tip is
+left on the local branch
+.BI dgit/ suite
+ready for work, and on the corresponding dgit remote tracking branch.
+Also, the
+.B origin
+remote will be set up to point to the package's dgit-repos tree
+for the distro to which
+.I suite
+belongs.
+.TP
+\fBdgit fetch\fR [\fIsuite\fP]
+Consults the archive and git-repos to update the git view of
+history for a specific suite (and downloads any necessary orig
+tarballs), and updates the remote tracking branch
+.BR remotes/dgit/dgit/ \fIsuite\fR.
+If the current branch is
+.BI dgit/ suite
+then dgit fetch defaults to
+.IR suite ;
+otherwise it parses debian/changelog and uses the suite specified
+there.
+.TP
+\fBdgit pull\fR [\fIsuite\fP]
+Does dgit fetch, and then merges the new head of the remote tracking
+branch
+.BI remotes/dgit/dgit/ suite
+into the current branch.
+.TP
+\fBdgit build\fR ...
+Runs
.B git-buildpackage
-with some suitable options. Options after
-.B build
-will be passed on to git-buildpackage. It is not necessary to
-use dgit build; it is OK to use any approach which ensures that
-the generated source package corresponds to the relevant git commit.
-Tagging and signing should be left to dgit push.
+with some suitable options. Options and argumments after build
+will be passed on to git-buildpackage. It is not necessary to use
+dgit build when using dgit; it is OK to use any approach which ensures
+that the generated source package corresponds to the relevant git
+commit.
+
+.B NB
+that this function will be changed in the future to use
+dpkg-buildpackage directly.
+
+Tagging, signing and actually uploading should be left to dgit push.
+.TP
+\fBdgit build-source\fR ...
+Builds the source package, and a changes file for a prospective
+source-only upload. The output is left in
+.IR package \fB_\fR version \fB.dsc\fR
+and
+.IR package \fB_\fR version \fB_source.changes\fR.
+Tagging, signing and actually uploading should be left to dgit push.
+.TP
+\fBdgit sbuild\fR ...
+Constructs the source package, and uses 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
+.IR package \fB_\fR version \fB_multi.changes\fR.
+
+Tagging, signing and actually uploading should be left to dgit push.
+.TP
.B dgit push
-does an `upload', pushing the current HEAD to the archive (as a source
-package) and to dgit-repos (as git commits). This also involves
-making a signed git tag, and signing the files to be uploaded to the
-archive. (For a format `3.0 (quilt)' source package, dgit push
+Does an `upload', pushing the current HEAD to the archive (as a source
+package) and to dgit-repos (as git commits). The package must already
+have been built ready for upload, with the .dsc and .changes
+left in the parent directory.
+
+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,
+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
+archive.
+
+For a format `3.0 (quilt)' source package, dgit push
may also have to make a commit on your current branch to contain
-quilt metadata. It will do this automatically.)
+quilt metadata. It will do this automatically if necessary.
+You can explicitly request that dgit do just this
+dgit quilt-fixup.
+
+dgit push always uses the package, suite and version specified in the
+debian/changelog and the .dsc, which must agree.
+If dgit push fails while uploading, it is fine to simply retry the
+dput on the .changes file at your leisure.
+.TP
.B dgit quilt-fixup
-looks to see if there is quilt patch metadata left over by dpkg-source
+Looks to see if there is quilt patch metadata left over by dpkg-source
-b, and if so makes a git commit of it. This is normally done
automatically by dgit push. dgit quilt-fixup takes no additional
arguments. Note that it will only process a patch generated by
dpkg-source for the most recent version (according to the
debia/changelog).
+
+It is not normally necessary to run dgit quilt-fixup explicitly;
+where necessary it is done as part of dgit push.
.SH WORKFLOW - SIMPLE
It is always possible with dgit to clone or fetch a package, make
changes in git (using git-commit) on the suite branch
to construct the commit to push; the only requirement is that it is a
descendant of the state of the archive, as provided by dgit in the
remote tracking branch
-.BR remotes/dgit/ \fIsuite\fR.
+.BR remotes/dgit/dgit/ \fIsuite\fR.
If you are lucky the other uploaders have also used dgit and
integrated the other relevant git history; if not you can fetch it
.B dgit fetch
(or clone) to obtain a git history representation of what's in the
archive and record it in the
-.BI remotes/dgit/ suite
+.BI remotes/dgit/dgit/ suite
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
dig remote tracking branch, check it out and say
-.BR "git merge -s ours remotes/dgit/" \fIsuite\fR;
+.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.
Then run
normally the dgit-repos repo for the package will be accessible via
the remote name `origin'.
+dgit push will also (by default) make signed tags called
+.BI debian/ version
+and push them to dgit-repos, but nothing depends on these tags
+existing.
+
dgit push can operate on any commit which is a descendant of the
current dgit/suite tip in dgit-repos.
Secondly, you can regard your quiltish patch stack in the archive as
primary. You will have to use other tools besides dgit to import and
export this patch stack. For `3.0 (quilt)' packages, dgit has to do
-more work to work around quilt braindamage. See also the BUGS
-section. We recommend against the use of `3.0 (quilt)'.
+more work to work around some braindamage in way dpkg-source handles
+changes made to this format. See also the BUGS section. We recommend
+against the use of `3.0 (quilt)'.
.SH OPTIONS
.TP
.BR --dry-run | -n
rather than looking in debian/control or debian/changelog.
Valid with dgit fetch and dgit pull, only.
.TP
+.BR --clean=git | -wg
+The source tree should be cleaned, before building a source package
+with one of the build options, using
+.BR "git clean -xdf" .
+This will delete all files which are not tracked by git.
+.TP
+.BR --clean=none | -wn
+Do not clean the tree before building a source package. If there are
+files which are not in git, a subsequent dgit push will fail.
+.TP
+.BR --clean=dpkg-source | -wd
+Use dpkg-buildpackage to do the build, so that the source package
+is cleaned by dpkg-source running the package's clean target.
+This is the default. It requires the package's build dependencies.
+.TP
.BR -N | --new
The package may be new in this suite. Without this, dgit will
refuse to push.
Specifies a git configuration option. dgit itself is also controlled
by git configuration options.
.TP
-.RI \fB--dget=\fR program |\fB--dput=\fR program |\fB--debsign=\fR program
-Specifies alternative programs to use instead of dget, dput
-or debsign.
-.TP
-.RI \fB--dget:\fR option |\fB--dput:\fR option |\fB--debsign:\fR option
-Specifies a single additional option to pass to dget, dput or
-debsign. Use repeatedly if multiple additional options are required.
+.RI \fB-v\fR version |\fB-m\fR maintaineraddress
+Passed to dpkg-genchanges (eventually).
+.TP
+.RI \fB--ch:\fR option
+Specifies a single additional option to pass, eventually, to
+dpkg-genchanges.
+.TP
+.RI \fB--dget=\fR program |\fB--dput=\fR program |...
+Specifies alternative programs to use instead of
+.BR dget ,
+.BR dput ,
+.BR debsign ,
+.BR dpkg-source ,
+.BR dpkg-buildpackage ,
+.BR dpkg-genchanges ,
+.BR sbuild ,
+or
+.BR mergechanges .
+This applies only when the program is invoked directly by dgit.
+.TP
+.RI \fB--dget:\fR option |\fB--dput:\fR option |...
+Specifies a single additional option to pass to
+.BR dget ,
+.BR dput ,
+.BR debsign ,
+.BR dpkg-source ,
+.BR dpkg-buildpackage ,
+.BR dpkg-genchanges ,
+.BR sbuild ,
+or
+.BR mergechanges .
+Can be repeated as necessary.
+This applies only when the program is invoked directly by dgit.
+Usually, for passing options to dpkg-genchanges, use
+.BR --ch: \fIoption\fR.
+.TP
+.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
+.BR dgit-suite. \fIsuite\fR .distro .
+The only effect is that other configuration variables (used
+for accessing the archive and dgit-repos) used are
+.BR dgit-distro. \fIdistro\fR .* .
+
+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
+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
+for fetching (and, for dgit push, altering) a variety of information both
+in the archive and in dgit-repos. How to do this is not yet
+documented, and currently the arrangements are unpleasant. See
+BUGS.
.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
-filename suggests it is for the right package and version.
+filename suggests it is for the right package and version - or,
+if there is a _multi.changes file, dgit uses that.
.TP
.BI --existing-package= package
dgit push needs to canonicalise the suite name. But currently
.TP
.BI dgit-distro. distro .ssh
.TP
+.BI dgit-distro. distro .keyid
+.TP
.BR dgit.default. *
for each
.BR dgit-distro. \fIdistro\fR . *
identical. That this is necessary is a bug in the `3.0 (quilt)'
format.
-The error messages are often unhelpfully terse and tend to refer to
-line numbers in dgit.
+There should be an option which arranges for the `3.0 (quilt)'
+autocommit to not appear on your HEAD, but instead only in the
+remote tracking suite branch.
+
+There should at the very least be some advice in the manpage about how
+to use dgit when the signing key is not available on the same machine
+as the build host.
The option parser requires values to be cuddled to the option name.