test suite: tar up the artifacts, and name the tarball after the test

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index f15fecf964448a3730e7ad52d975e5d40199af0b..1460938a4e5f329be38385b287b9683b01f12671 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -14,7 +14,7 @@ dgit \- git integration with the Debian archive
 .br
 .B dgit
 [\fIdgit\-opts\fP] \fBbuild\fP|\fBsbuild\fP|\fBbuild-source\fP
-[\fIbuild\-opts\fp]
+[\fIbuild\-opts\fP]
 .br
 .B dgit
 [\fIdgit\-opts\fP] \fBpush\fP|\fBpush-source\fP [\fIdgit\-opts\fP]
@@ -46,6 +46,7 @@ dgit-maint-debrebase(7)       for maintainers: a pure-git rebasish workflow
 dgit-maint-merge(7)    for maintainers: a pure-git merging workflow
 dgit-maint-gbp(7)      for maintainers already using git-buildpackage
 dgit-sponsorship(7)    for sponsors and sponsored contributors
+dgit-downstream-dsc(7) setting up dgit push for a new distro
 .TE
 .LP
 See \fBdgit(7)\fP for detailed information about the data
@@ -109,6 +110,27 @@ branch
 .BI remotes/dgit/dgit/ suite
 into the current branch.
 .TP
+\fBdgit checkout\fR \fIsuite\fR
+Checks out the local branch
+.BR dgit/ \fIsuite\fR.
+
+If the branch does not exist,
+dgit checkout creates it,
+and sets it up the same way as dgit clone would.
+In that case, if
+the archive remote tracking branch does not exist,
+dgit checkout will do a dgit fetch first.
+
+NB: dgit checkout will only do a fetch if it has to.
+If you already have the suite branch,
+and want to merge your branch with updates from the archive,
+use dgit pull.
+
+dgit checkout will normally need to aceess the archive server,
+to canonicalise the provided suite name.
+The exception is if you specify the canonical name,
+and the branch (or tracking branch) already exists.
+.TP
 \fBdgit build\fR ...
 Runs
 .B dpkg-buildpackage
@@ -206,9 +228,6 @@ dgit push always uses the package, suite and version specified in the
 debian/changelog and the .dsc, which must agree.  If the command line
 specifies a suite then that must match too.
 
-With \fB-C\fR, performs a dgit push, additionally ensuring that no
-binary packages are uploaded.
-
 When used on a git-debrebase branch,
 dgit calls git-debrebase
 to prepare the branch
@@ -218,6 +237,9 @@ for source package upload and push.
 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."
+
+With \fB-C\fR, performs a dgit push, additionally ensuring that no
+binary packages are uploaded.
 .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.
@@ -514,11 +536,15 @@ push will still ensure that the .dsc you upload and the git tree
 you push are identical, so this option won't make broken pushes.)
 .TP
 .BR --overwrite [=\fIprevious-version\fR]
-Declare that even though your git branch may not be a descendant
+Declare that your HEAD really does contain
+all the (wanted) changes
+from all versions listed in its changelog;
+or, all (wanted) changes from
+.IR previous-version .
+This promise is needed when
+your git branch is not a descendant
 of the version in the archive
-according to the revision history,
-it really does contain
-all the (wanted) changes from that version.
+according to the git revision history.
 
 This option is useful if you are the maintainer, and you have
 incorporated NMU changes into your own git workflow in a way that
@@ -530,15 +556,19 @@ to a particular suite.
 See
 .BR dgit-maint- \fI*\fR (7) .
 
-.I previous-version
-ought to be the version currently in the archive.  If
+If
 .I previous-version
 is not
 specified, dgit will check that the version in the archive is
 mentioned in your debian/changelog.
 (This will avoid losing
-changes unless someone committed to git a finalised changelog
+changes, even with
+.BR --overwrite ,
+unless someone committed to git a finalised changelog
 entry, and then made later changes to that version.)
+If
+.IR previous-version
+is specified, it ought to be the version currently in the archive.
 
 dgit push --overwrite
 will, if necessary, make a
@@ -1021,6 +1051,17 @@ The result is a fresh import,
 discarding the git history
 that the person who pushed that .dsc was working with.
 .TP
+.B --force-uploading-binaries
+Carry on and
+upload binaries
+even though dgit thinks your distro does not permit that.
+.TP
+.B --force-uploading-source-only
+Carry on and do a source-only upload,
+without any binaries,
+even though dgit thinks your distro does not permit that,
+or does not permit that in this situation.
+.TP
 .B --force-unrepresentable
 Carry on even if
 dgit thinks that your git tree contains changes
@@ -1197,6 +1238,8 @@ or when pushing and
 .TP
 .BI dgit-distro. distro .rewrite-map-enable
 .TP
+.BR dgit-distro. \fIdistro\fR .source-only-uploads " " ok | always | never | not-wholly-new
+.TP
 .BI dgit.default.old-dsc-distro
 .TP
 .BI dgit.dsc-url-proto-ok. protocol