.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]
.B dgit-repos
which lives outside the Debian archive (currently, on Alioth).
+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]
+\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
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.
+.BR remotes/dgit/dgit/ \fIsuite\fR.
If the current branch is
.BI dgit/ suite
then dgit fetch defaults to
\fBdgit pull\fR [\fIsuite\fP]
Does dgit fetch, and then merges the new head of the remote tracking
branch
-.BI remotes/dgit/ suite
+.BI remotes/dgit/dgit/ suite
into the current branch.
.TP
\fBdgit build\fR ...
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
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
.BR mergechanges .
Can be repeated as necessary.
.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 . *