Tagging, signing and actually uploading should be left to dgit push.
.TP
-.B dgit push
+\fBdgit push\fR [\fIsuite\fP]
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
archive.
dgit push always uses the package, suite and version specified in the
-debian/changelog and the .dsc, which must agree.
+debian/changelog and the .dsc, which must agree. If the command line
+specifies a suite then that must match too.
If dgit push fails while uploading, it is fine to simply retry the
dput on the .changes file at your leisure.
.BR dpkg-buildpackage ,
.BR dpkg-genchanges ,
.BR sbuild ,
+.BR gpg ,
+.BR ssh ,
or
.BR mergechanges .
-This applies only when the program is invoked directly by dgit.
+
+For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild,
+this applies only when the program is invoked directly by dgit.
+
+For ssh, the default value is taken from the
+.B DGIT_SSH
+or
+.B GIT_SSH
+environment variables, if set (see below). And, for ssh, when accessing the
+archive and dgit-repos, this command line setting is overridden by the
+git config variables
+.BI dgit-distro. distro .ssh
+and
+.B .dgit.default.ssh
+(which can in turn be overridden with -c). Also, when dgit is using
+git to access dgit-repos, only git's idea of what ssh to use (eg,
+.BR GIT_SSH )
+is relevant.
.TP
.RI \fB--dget:\fR option |\fB--dput:\fR option |...
Specifies a single additional option to pass to
.BR dpkg-buildpackage ,
.BR dpkg-genchanges ,
.BR sbuild ,
+.BR ssh ,
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
+
+For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild,
+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.
+
+See note above regarding ssh.
+
+NB that --gpg:option is not supported (because debsign does not
+have that facility). But see -k.
.TP
.BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
Specifies that the suite to be operated on is part of distro
.BR dgit.default. *
for each
.BR dgit-distro. \fIdistro\fR . *
+.SH ENVIRONMENT VARIABLES
+.TP
+.BR DGIT_SSH ", " GIT_SSH
+specify an alternative default program (and perhaps arguments) to use
+instead of ssh. DGIT_SSH is consulted first and may contain arguments;
+if it contains any whitespace will be passed to the shell. GIT_SSH
+specifies just the program; no arguments can be specified, so dgit
+interprets it the same way as git does.
+See
+also the --ssh= and --ssh: options.
+.TP
+.BR gpg ", " dpkg- "..., " debsign ", " git ", " dget ", " dput ", " LWP::UserAgent
+and other subprograms and modules used by dgit are affected by various
+environment variables. Consult the documentaton for those programs
+for details.
.SH BUGS
We should be using some kind of vhost/vpath setup for the git repos on
alioth, so that they can be moved later if and when this turns out to