Manpage formatting fix.

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index eb5b2c11d6702aa1451663747117e08d72913bfe..319ce2521d0d5c5ae9b6c81ec1a1f120b358cf35 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -5,15 +5,15 @@ dgit \- git integration with the Debian archive
 .SH SYNOPSIS
 .B dgit
 [\fIdgit\-opts\fP] \fBclone\fP [\fIdgit\-opts\fP]
 .SH SYNOPSIS
 .B dgit
 [\fIdgit\-opts\fP] \fBclone\fP [\fIdgit\-opts\fP]

-\fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir]
+\fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]

 .br
 .B dgit
 [\fIdgit\-opts\fP] \fBfetch\fP|\fBpull\fP [\fIdgit\-opts\fP]
 [\fIsuite\fP]
 .br
 .B dgit
 .br
 .B dgit
 [\fIdgit\-opts\fP] \fBfetch\fP|\fBpull\fP [\fIdgit\-opts\fP]
 [\fIsuite\fP]
 .br
 .B dgit

-[\fIdgit\-opts\fP] \fBbuild\fP
-[\fIgit\-buildpackage\-opts\fP|\fIdpkg\-buildpackage\-opts\fp]
+[\fIdgit\-opts\fP] \fBbuild\fP|\fBsbuild\fP
+[\fIbuild\-opts\fp]

 .br
 .B dgit
 [\fIdgit\-opts\fP] \fBpush\fP [\fIdgit\-opts\fP]
 .br
 .B dgit
 [\fIdgit\-opts\fP] \fBpush\fP [\fIdgit\-opts\fP]


@@ -32,8 +32,12 @@ as
 .B dgit-repos
 which lives outside the Debian archive (currently, on Alioth).
 
 .B dgit-repos
 which lives outside the Debian archive (currently, on Alioth).
 

+The usual workflow is: 1. clone or fetch; 2. make and commit changes
+in git as desired; 3. run dgit build or dgit sbuild, or generate the
+source and binary packages for upload some other way; 4. do
+pre-upload tests of the proposed upload; 5. run dgit push.

 .TP
 .TP

-\fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir]
+\fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]

 Consults the archive and dgit-repos to construct the git view of
 history for
 .I package
 Consults the archive and dgit-repos to construct the git view of
 history for
 .I package


@@ -78,13 +82,21 @@ into the current branch.
 \fBdgit build\fR ...
 Runs
 .B git-buildpackage
 \fBdgit build\fR ...
 Runs
 .B git-buildpackage

-with some suitable options.  Options and argumments after
-.B build
+with some suitable options.  Options and argumments after build

 will be passed on to git-buildpackage.  It is not necessary to use
 dgit build when using dgit; it is OK to use any approach which ensures
 that the generated source package corresponds to the relevant git
 commit.  Tagging and signing should be left to dgit push.
 .TP
 will be passed on to git-buildpackage.  It is not necessary to use
 dgit build when using dgit; it is OK to use any approach which ensures
 that the generated source package corresponds to the relevant git
 commit.  Tagging and signing should be left to dgit push.
 .TP

+\fBdgit sbuild\fR ...
+Constructs the source package, and uses sbuild to do a binary
+build, and uses mergechanges to merge the source and binary
+changes files.  Options and argumments after sbuild will be passed on
+to sbuild.  Changes files matching
+.IB package _ version _*.changes
+in the parent directory will be removed; the output is left in
+.IR package \fB_\fR version \fB_multi.changes\fR.
+.TP

 .B dgit push
 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
 .B dgit push
 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


@@ -106,6 +118,9 @@ dgit quilt-fixup.
 
 dgit push always uses the package, suite and version specified in the
 debian/changelog and the .dsc, which must agree.
 
 dgit push always uses the package, suite and version specified in the
 debian/changelog and the .dsc, which must agree.

+
+If dgit push fails while uploading, it is fine to simply retry the
+dput on the .changes file at your leisure.

 .TP
 .B dgit quilt-fixup
 Looks to see if there is quilt patch metadata left over by dpkg-source
 .TP
 .B dgit quilt-fixup
 Looks to see if there is quilt patch metadata left over by dpkg-source


@@ -285,18 +300,53 @@ more output (currently, up to -DD is meaningfully different).
 Specifies a git configuration option.  dgit itself is also controlled
 by git configuration options.
 .TP
 Specifies a git configuration option.  dgit itself is also controlled
 by git configuration options.
 .TP

-.RI \fB--dget=\fR program |\fB--dput=\fR program |\fB--debsign=\fR program
-Specifies alternative programs to use instead of dget, dput
-or debsign.
-.TP
-.RI \fB--dget:\fR option |\fB--dput:\fR option |\fB--debsign:\fR option
-Specifies a single additional option to pass to dget, dput or
-debsign.  Use repeatedly if multiple additional options are required.
+.RI \fB--dget=\fR program |\fB--dput=\fR program |...
+Specifies alternative programs to use instead of
+.BR dget ,
+.BR dput ,
+.BR debsign ,
+.BR dpkg-buildpackage
+.BR sbuild ,
+or
+.BR mergechanges .
+.TP
+.RI \fB--dget:\fR option |\fB--dput:\fR option |...
+Specifies a single additional option to pass to
+.BR dget ,
+.BR dput ,
+.BR debsign ,
+.BR dpkg-buildpackage
+.BR sbuild ,
+or
+.BR mergechanges .
+Can be repeated as necessary.
+.TP
+.BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
+Specifies that the suite to be operated on is part of distro
+.IR distro .
+This overrides the default value found from the git config option
+.BR dgit-suite. \fIsuite\fR .distro .
+The only effect is that other configuration variables (used
+for accessing the archive and dgit-repos) used are
+.BR dgit-distro. \fIdistro\fR .* .
+
+If your suite is part of a distro that dgit already knows about, you
+can use this option to make dgit work even if your dgit doesn't know
+about the suite.  For example, specifying
+.B -ddebian
+will work when the suite is an unknown suite in the Debian archive.
+
+To define a new distro it is necessary to define methods and URLs
+for fetching (and, for dgit push, altering) a variety of information both
+in the archive and in dgit-repos.  How to do this is not yet
+documented, and currently the arrangements are unpleasant.  See
+BUGS.

 .TP
 .BI -C changesfile
 Specifies the .changes file which is to be uploaded.  By default
 dgit push looks for single .changes file in the parent directory whose
 .TP
 .BI -C changesfile
 Specifies the .changes file which is to be uploaded.  By default
 dgit push looks for single .changes file in the parent directory whose

-filename suggests it is for the right package and version.
+filename suggests it is for the right package and version - or,
+if there is a _multi.changes file, dgit uses that.

 .TP
 .BI --existing-package= package
 dgit push needs to canonicalise the suite name.  But currently
 .TP
 .BI --existing-package= package
 dgit push needs to canonicalise the suite name.  But currently


@@ -361,6 +411,8 @@ on the dgit command line.
 .TP
 .BI dgit-distro. distro .ssh
 .TP
 .TP
 .BI dgit-distro. distro .ssh
 .TP

+.BI dgit-distro. distro .keyid
+.TP

 .BR dgit.default. *
 for each
 .BR dgit-distro. \fIdistro\fR . *
 .BR dgit.default. *
 for each
 .BR dgit-distro. \fIdistro\fR . *