dgit(1): Reword push-source vs push description

Move the principal description into push-source, and make the
necessary consequential changes.

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

1 files changed, 30 insertions, 16 deletions

diff --git a/dgit.1 b/dgit.1
index a356190..c3a6c68 100644
--- a/dgit.1
+++ b/dgit.1
@@ -235,24 +235,15 @@ git-buildpackage style branch, not a patches-applied branch.
 Tagging, signing and actually uploading should be left to dgit push.
 .TP
 \fBdgit push-source\fR [\fIsuite\fP]
-Without \fB\-C\fR, builds a source package and dgit pushes it.  Saying
-\fBdgit push-source\fR is like saying "update the source code in the
-archive to match my git HEAD, and let the autobuilders do the rest."
+Does an `upload': sends the current HEAD
+to dgit-repos (as git commits),
+and to the archive (as a source package, built by dgit push-source).
 
-With \fB\-C\fR, performs a dgit push-source, additionally ensuring that no
-binary packages are uploaded.
-.TP
-\fBdgit push-built\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
-left in the parent directory.  It is normally best to do the build
-with dgit too (eg with dgit sbuild): some existing build tools pass
-unhelpful options to dpkg-source et al by default, which can result in
-the built source package not being identical to the git tree.
+This is the usual way to upload to Debian.
 
-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,
+In more detail: dgit push-source
+builds a source package from HEAD.
+It then pushes the HEAD to the suite's dgit-repos branch,
 adjusts the .changes to include any .origs which the archive lacks
 and exclude .origs which the archive has
 (so \-sa and \-sd are not needed when building for dgit push),
@@ -269,6 +260,29 @@ When used on a git-debrebase branch,
 dgit calls git-debrebase
 to prepare the branch
 for source package upload and push.
+
+With \fB\-C\fR, dgit push-source performs a dgit push-built,
+additionally ensuring that no
+binary packages are uploaded.
+.TP
+\fBdgit push-built\fR [\fIsuite\fP]
+Does an `upload' of a previously built package,
+possibly including binaries.
+Sends the current HEAD to dgit-repos (as git commits);
+and, sends the previously built source package and binaries
+to the archive.
+
+The package must already
+have been built ready for upload, with the .dsc and .changes
+left in the parent directory.  It is normally best to do the build
+with dgit too (eg with dgit sbuild): some existing build tools pass
+unhelpful options to dpkg-source et al by default, which can result in
+the built source package not being identical to the git tree.
+
+dgit will check that the .dsc corresponds exactly to the current HEAD,
+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]
 Pushes the contents of the specified directory on a remote machine.