dgit(1): Document rpush-source and new rpush behaviour

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

1 files changed, 26 insertions, 12 deletions

diff --git a/dgit.1 b/dgit.1
index c3a6c68..e59cf6a 100644
--- a/dgit.1
+++ b/dgit.1
@@ -25,7 +25,7 @@ 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
+[\fIdgit\-opts\fP] \fBrpush\fR|\fBrpush-built\fP \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR
 [\fIpush args...\fR]
 .br
 .B dgit
@@ -284,12 +284,12 @@ ensuring that all users whether of the dgit git view,
 or of the traditional archive,
 see the same source package.
 .TP
-\fBdgit rpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR [\fIpush args...\fR]
+\fBdgit rpush-source\fR|\fBrpush-built\fR \fIbuild-host\fR\fB:\fR\fIsrc-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
+This is like running dgit push on build-host with src-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:
+the source code (and any built binaries) has no access to the key:
 
 .TS
 l l.
@@ -304,7 +304,8 @@ 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
+The remaining arguments are treated just as dgit push-source
+or dgit push-built would handle
 them.
 
 build-host and build\-dir can be passed as separate
@@ -316,14 +317,18 @@ You will need similar enough versions of dgit on the build-host and
 the invocation host.  The build-host needs gnupg installed, with your
 public key in its keyring (but not your private key, obviously).
 .TP
-\fBdgit push\fR \fI...\fP
-Configurable alias for
-.BR "dgit push-built" ,
+\fBdgit push\fR|\fBrpush\fR \fI...\fP
+Configurable aliases for
+.BR "dgit push-built"
+and
+.BR "dgit rpush-built" ,
 which will in the future change to mean
-.BR "dgit push-source" ,
-and therefore currently generates a warning.
+.BR "dgit push-source"
+and
+.BR "dgit rpush-source" ,
+and therefore currently generate a warning.
 
-The behaviour is controlled by the
+The behaviour of dgit push is controlled by the
 .B dgit.default.push-subcmd
 git config option:
 .TS
@@ -334,7 +339,16 @@ l l l .
 \fBreject\fR	fails
 .TE
 
-That setting can safely be passed to older dgit (via
+For dgit rpush, the behaviour is controlled by
+.BR dgit.default.rpush-subcmd ,
+falling back to 
+.BR dgit.default.push-subcmd
+if that is not set.
+Because dgit rpush is not typically run in a git working tree,
+only global git config options
+(and \fB-c\fR command line options) are relevant.
+
+These settings can safely be passed to older dgit (via
 .BR -c);
 the value
 .B built