[\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
+[\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 or dgit sbuild, 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]
+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/ \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/ 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. Tagging and signing 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.
+.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.
+.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
If last upload was not made with git, a different approach is required
to start using dgit. First, do
.B dgit fetch
-(or clone) obtain a git history representation of what's in the
+(or clone) to obtain a git history representation of what's in the
archive and record it in the
.BI remotes/dgit/ suite
-tracking branch. Then construct somehow, using your other git history
+tracking branch. Then somehow, using your other git history
plus appropriate diffs and cherry picks from the dgit remote tracking
-branch, a git commit whose tree corresponds to the tree to use for the
+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;
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
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.
+.RI \fB--dget=\fR program |\fB--dput=\fR program |...
+Specifies alternative programs to use instead of
+.BR dget ,
+.BR dput ,
+.BR debsign ,
+.BR dpkg-buildpackage
+.BR sbuild ,
+or
+.BR mergechanges .
.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--dget:\fR option |\fB--dput:\fR option |...
+Specifies a single additional option to pass to
+.BR dget ,
+.BR dput ,
+.BR debsign ,
+.BR dpkg-buildpackage
+.BR sbuild ,
+or
+.BR mergechanges .
+Can be repeated as necessary.
.TP
.BI -C changesfile
Specifies the .changes file which is to be uploaded. By default
we guess
.B dpkg
or use the value of this option.
+.TP
+.BR -h | --help
+Print a usage summary.
+.SH SEE ALSO
+\fBdget\fP(1),
+\fBdput\fP(1),
+\fBdebsign\fP(1),
+\fBgit-config\fP(1),
+\fBgit-buildpackage\fP(1),
+\fBdpkg-buildpackage\fP(1),
+.br
+https://wiki.debian.org/Alioth
.SH CONFIGURATION
dgit looks at the following git config keys to control its behaviour.
You may set them with git-config (either in system-global or per-tree
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.