X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=322bc3b0ab27862663bc302da08a52cae2d71206;hp=ee78e1b481fc77da035d60ae20490356b2912741;hb=98cc9f5ee0e1a448c10dbee264fa8ada8d023e54;hpb=377e1c315cc73e5364506cf5eb601de130f72c77

diff --git a/dgit.1 b/dgit.1
index ee78e1b4..322bc3b0 100644
--- a/dgit.1
+++ b/dgit.1
@@ -5,14 +5,14 @@ dgit \- git integration with the Debian archive
 .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
-[\fIdgit\-opts\fP] \fBbuild\fP|\fBsbuild\fP
+[\fIdgit\-opts\fP] \fBbuild\fP|\fBsbuild\fP|\fBbuild-source\fP
 [\fIbuild\-opts\fp]
 .br
 .B dgit
@@ -33,11 +33,12 @@ as
 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.
+in git as desired; 3. run dgit build, dgit sbuild or dgit
+build-source, 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
-\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
@@ -65,7 +66,7 @@ belongs.
 Consults the archive and git-repos to update the git view of
 history for a specific suite (and downloads any necessary orig
 tarballs), and updates the remote tracking branch
-.BR remotes/dgit/ \fIsuite\fR.
+.BR remotes/dgit/dgit/ \fIsuite\fR.
 If the current branch is
 .BI dgit/ suite
 then dgit fetch defaults to
@@ -76,7 +77,7 @@ there.
 \fBdgit pull\fR [\fIsuite\fP]
 Does dgit fetch, and then merges the new head of the remote tracking
 branch
-.BI remotes/dgit/ suite
+.BI remotes/dgit/dgit/ suite
 into the current branch.
 .TP
 \fBdgit build\fR ...
@@ -86,7 +87,22 @@ 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.
+commit.
+
+.B NB
+that this function will be changed in the future to use
+dpkg-buildpackage directly.
+
+Tagging, signing and actually uploading should be left to dgit push.
+.TP
+\fBdgit build-source\fR ...
+Builds the source package, and a changes file for a prospective
+source-only upload.  The output is left in
+.IR package \fB_\fR version \fB.dsc\fR
+and
+.IR package \fB_\fR version \fB_source.changes\fR.
+
+Tagging, signing and actually uploading should be left to dgit push.
 .TP
 \fBdgit sbuild\fR ...
 Constructs the source package, and uses sbuild to do a binary
@@ -96,6 +112,8 @@ 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.
+
+Tagging, signing and actually uploading should be left to dgit push.
 .TP
 .B dgit push
 Does an `upload', pushing the current HEAD to the archive (as a source
@@ -140,7 +158,7 @@ and then dgit push.  You can use whatever gitish techniques you like
 to construct the commit to push; the only requirement is that it is a
 descendant of the state of the archive, as provided by dgit in the
 remote tracking branch
-.BR remotes/dgit/ \fIsuite\fR.
+.BR remotes/dgit/dgit/ \fIsuite\fR.
 
 If you are lucky the other uploaders have also used dgit and
 integrated the other relevant git history; if not you can fetch it
@@ -175,13 +193,13 @@ to start using dgit.  First, do
 .B dgit fetch
 (or clone) to obtain a git history representation of what's in the
 archive and record it in the
-.BI remotes/dgit/ suite
+.BI remotes/dgit/dgit/ suite
 tracking branch.  Then somehow, using your other git history
 plus appropriate diffs and cherry picks from the dgit remote tracking
 branch, construct a git commit whose tree corresponds to the tree to use for the
 next upload.  If that commit-to-be-uploaded is not a descendant of the
 dig remote tracking branch, check it out and say
-.BR "git merge -s ours remotes/dgit/" \fIsuite\fR;
+.BR "git merge -s ours remotes/dgit/dgit/" \fIsuite\fR;
 that tells git that we are deliberately throwing away any differences
 between what's in the archive and what you intend to upload.
 Then run
@@ -288,6 +306,21 @@ Specifies that we should process source package
 rather than looking in debian/control or debian/changelog.
 Valid with dgit fetch and dgit pull, only.
 .TP
+.BR --clean=git | -wg
+The source tree should be cleaned, before building a source package
+with one of the build options, using
+.BR "git clean -xdf" .
+This will delete all files which are not tracked by git.
+.TP
+.BR --clean=none | -wn
+Do not clean the tree before building a source package.  If there are
+files which are not in git, a subsequent dgit push will fail.
+.TP
+.BR --clean=dpkg-source | -wd
+Use dpkg-buildpackage to do the build, so that the source package
+is cleaned by dpkg-source running the package's clean target.
+This is the default.  It requires the package's build dependencies.
+.TP
 .BR -N | --new
 The package may be new in this suite.  Without this, dgit will
 refuse to push.
@@ -300,26 +333,41 @@ 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
+Passed to dpkg-genchanges (eventually).
+.TP
+.RI \fB--ch:\fR option
+Specifies a single additional option to pass, eventually, to
+dpkg-genchanges.
+.TP
 .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 dpkg-source ,
+.BR dpkg-buildpackage ,
+.BR dpkg-genchanges ,
 .BR sbuild ,
 or
 .BR mergechanges .
+This applies only when the program is invoked directly by dgit.
 .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 dpkg-source ,
+.BR dpkg-buildpackage ,
+.BR dpkg-genchanges ,
 .BR sbuild ,
 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
+.BR --ch: \fIoption\fR.
 .TP
 .BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
 Specifies that the suite to be operated on is part of distro