X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=dgit.1;h=c261300f555bd92a3a5c53184edd66ed9a7f28bb;hb=6e24ac7bb85e30df00b3d14853b049e3f06b6dec;hp=3c1a8f00b8a359bac2d784e6cd607d0a2f1306d6;hpb=c36579b521a6e6da1992e0bad826cd83560308d1;p=dgit.git

diff --git a/dgit.1 b/dgit.1
index 3c1a8f00..c261300f 100644
--- a/dgit.1
+++ b/dgit.1
@@ -20,6 +20,10 @@ dgit \- git integration with the Debian archive
 [\fIsuite\fP]
 .br
 .B dgit
+[\fIdgit\-opts\fP] \fBrpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR
+[\fIpush args...\fR]
+.br
+.B dgit
 [\fIdgit\-opts\fP] \fIaction\fR ...
 .SH DESCRIPTION
 .B dgit
@@ -125,7 +129,7 @@ will be passed on to git-buildpackage.
 
 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
@@ -139,11 +143,31 @@ signed tag, and finally uses dput to upload the .changes to the
 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.
 .TP
+\fBdgit rpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR [\fIpush args...\fR]
+Pushes the contents of the specified directory on a remote machine.
+This is like running dgit push on build-host with build-dir as the
+current directory; however, signing operations are done on the
+invoking host.  This allows you to do a push when the system which has
+the source code and the build outputs has no access to the key.
+
+However, the build-host must be able to ssh to the dgit repos.  If
+this is not already the case, you must organise it separately, for
+example by the use of ssh agent forwarding.
+
+The remaining arguments are treated just as dgit push would handle
+them.
+
+build-host and build\-dir can be passed as separate
+arguments; this is assumed to be the case if the first argument
+contains no : (except perhaps on in [ ], to support IPv6 address
+literals).
+.TP
 .B dgit quilt-fixup
 Looks to see if the tree is one which dpkg-source cannot properly
 represent.  If it isn't, dgit will fix it up for you (in quilt terms,
@@ -224,7 +248,22 @@ more output (currently, up to -DD is meaningfully different).
 Specifies a git configuration option.  dgit itself is also controlled
 by git configuration options.
 .TP
-.RI \fB-v\fR version |\fB-m\fR maintaineraddress
+.RI \fB-v\fR version "|\fB_\fR | " \fB--since-version=\fR version |\fB_\fR
+Specifies the
+.BI -v version
+option to pass to dpkg-genchanges, during builds.  Changes (from
+debian/changelog) since this version will be included in the built
+changes file, and hence in the upload.  If this option is not
+specified, dgit will query the archive and use the latest version
+uploaded to the intended suite.
+
+Specifying
+.B _
+inhibits this, so that no -v option will be passed to dpkg-genchanges
+(and as a result, only the last stanza from debian/changelog will
+be used for the build and upload).
+.TP
+.RI \fB-m\fR maintaineraddress
 Passed to dpkg-genchanges (eventually).
 .TP
 .RI \fB--ch:\fR option
@@ -240,9 +279,34 @@ Specifies alternative programs to use instead of
 .BR dpkg-buildpackage ,
 .BR dpkg-genchanges ,
 .BR sbuild ,
+.BR gpg ,
+.BR ssh ,
+.BR dgit ,
 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 dgit, specifies the command to run on the remote host when dgit
+rpush needs to invoke a remote copy of itself.  (dgit also reinvokes
+itself as the EDITOR for dpkg-source --commit; this is done using
+argv[0], and is not affected by --dget=).
+
+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
@@ -253,12 +317,21 @@ Specifies a single additional option to pass to
 .BR dpkg-buildpackage ,
 .BR dpkg-genchanges ,
 .BR sbuild ,
+.BR ssh ,
+.BR dgit ,
 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 notes above regarding ssh and dgit.
+
+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
@@ -298,6 +371,15 @@ or use the value of this option.
 .TP
 .BR -h | --help
 Print a usage summary.
+.TP
+.BI --initiator-tempdir= directory
+dgit rpush uses a temporary directory on the invoking (signing) host.
+This option causes dgit to use
+.I directory
+instead.  Furthermore, the specified directory will be emptied,
+removed and recreated before dgit starts, rather than removed
+after dgit finishes.  The directory specified must be an absolute
+pathname.
 .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
@@ -543,6 +625,21 @@ on the dgit command line.
 .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