Add Closes line for #720595 to changelog entry for 0.11. for using git-buildpackage...

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index 9b3ffb2cb517756bd4304b2f396fc9bf5fade3d6..9740856b215a59d62c8790743b3cb2faa2d2b023 100644 (file)
--- 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]
 .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|\fBsbuild\fP
+[\fIdgit\-opts\fP] \fBbuild\fP|\fBsbuild\fP|\fBbuild-source\fP

 [\fIbuild\-opts\fp]
 .br
 .B dgit
 [\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
 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
 .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


@@ -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
 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
 If the current branch is
 .BI dgit/ suite
 then dgit fetch defaults to


@@ -76,26 +77,50 @@ there.
 \fBdgit pull\fR [\fIsuite\fP]
 Does dgit fetch, and then merges the new head of the remote tracking
 branch
 \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 ...
 Runs
 into the current branch.
 .TP
 \fBdgit build\fR ...
 Runs

-.B git-buildpackage
+.B dpkg-buildpackage

 with some suitable options.  Options and argumments after build
 with some suitable options.  Options and argumments after build

-will be passed on to git-buildpackage.  It is not necessary to use
+will be passed on to dpkg-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
 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.
+
+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, using
+.BR dpkg-source .
+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 ...
 .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
+Constructs the source package, uses
+.B  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.
 .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
+\fBdgit git-build\fR ...
+Runs
+.B git-buildpackage
+with some suitable options.  Options and argumments after git-build
+will be passed on to git-buildpackage.
+
+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
 .TP
 .B dgit push
 Does an `upload', pushing the current HEAD to the archive (as a source


@@ -110,12 +135,6 @@ field, runs debsign to sign the upload (.dsc and .changes), pushes the
 signed tag, and finally uses dput to upload the .changes to the
 archive.
 
 signed tag, and finally uses dput to upload the .changes to the
 archive.
 

-For a format `3.0 (quilt)' source package, dgit push
-may also have to make a commit on your current branch to contain
-quilt metadata.  It will do this automatically if necessary.
-You can explicitly request that dgit do just this
-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.
 


@@ -123,15 +142,12 @@ 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
 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
--b, and if so makes a git commit of it.  This is normally done
-automatically by dgit push.  dgit quilt-fixup takes no additional
-arguments.  Note that it will only process a patch generated by
-dpkg-source for the most recent version (according to the
-debia/changelog).
-
-It is not normally necessary to run dgit quilt-fixup explicitly;
-where necessary it is done as part of dgit push.
+Looks to see if the tree is one which dpkg-source cannot properly
+represent.  If it isn't, dgit will fix it up for you (in quilt terms,
+by making a new debian/ patch containing your unquilty changes) and
+make a commit of the changes it has made.
+
+This is normally done automatically by dgit build and dgit push.

 .SH WORKFLOW - SIMPLE
 It is always possible with dgit to clone or fetch a package, make
 changes in git (using git-commit) on the suite branch
 .SH WORKFLOW - SIMPLE
 It is always possible with dgit to clone or fetch a package, make
 changes in git (using git-commit) on the suite branch


@@ -140,7 +156,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
 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
 
 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 +191,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
 .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
 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
 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


@@ -256,15 +272,34 @@ in git and a fast-forwarding release branch; or you could do your work
 directly in a merging way on the
 .BI dgit/ suite
 branches.  If you do this you should probably use a `1.0' format
 directly in a merging way on the
 .BI dgit/ suite
 branches.  If you do this you should probably use a `1.0' format

-source package.  In the archive, the delta between upstream will be
-represented in the single Debian patch.
-
-Secondly, you can regard your quiltish patch stack in the archive as
-primary.  You will have to use other tools besides dgit to import and
-export this patch stack.  For `3.0 (quilt)' packages, dgit has to do
-more work to work around some braindamage in way dpkg-source handles
-changes made to this format.  See also the BUGS section.  We recommend
-against the use of `3.0 (quilt)'.
+source package if you can.  In the archive, the delta between upstream
+will be represented in the single Debian patch.
+
+Secondly, you can use `3.0 (quilt)', and regard your quiltish patch
+stack in the archive as primary.  You will have to use other tools
+besides dgit to import and export this patch stack.  But see below:
+.SH FORMAT 3.0 (QUILT)
+For a format `3.0 (quilt)' source package, dgit may have to make a
+commit on your current branch to contain metadata used by quilt and
+dpkg-source.
+
+This is because (i) the `3.0 (quilt)' source format cannot represent
+certain trees, and (ii) packing up a tree in `3.0 (quilt)' and then
+unpacking it does not always yield the same tree.  Instead,
+dpkg-source insists on the trees having extra quilty metadata and
+patch files in the debian/ and .pc/ directories, which dpkg-source
+sometimes modifies.
+
+dgit will automatically work around this braindamage for you when
+building and pushing.  The only thing you need to know is that dgit
+build, sbuild, etc., may make a new commit on your HEAD.  If you're
+not a quilt user this commit won't contain any changes to files you
+care about.
+
+You can explicitly request that dgit do just this fixup, by running
+dgit quilt-fixup.
+
+We recommend against the use of `3.0 (quilt)'.

 .SH OPTIONS
 .TP
 .BR --dry-run | -n
 .SH OPTIONS
 .TP
 .BR --dry-run | -n


@@ -288,6 +323,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
 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.
 .BR -N | --new
 The package may be new in this suite.  Without this, dgit will
 refuse to push.


@@ -300,26 +350,62 @@ 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-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 ,
 .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 .
 .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 ,
 .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.
 .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
+.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
 .TP
 .BI -C changesfile
 Specifies the .changes file which is to be uploaded.  By default


@@ -390,6 +476,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 . *


@@ -442,14 +530,10 @@ the .orig.tar.gz could be transported via the git repo as git tags.
 Doing this is made more complicated by the possibility of a `3.0
 (quilt)' package with multiple .orig tarballs.
 
 Doing this is made more complicated by the possibility of a `3.0
 (quilt)' package with multiple .orig tarballs.
 

-`3.0 (quilt)' packages have an additional difficulty: if these are
-edited in the most normal way, and then fed to dpkg-buildpackage,
-dpkg-source will add extra quilt patch metadata to the source tree
-during the source package build.  This extra metadata is then of
-course not included in the git history.  So dgit push needs to commit
-it for you, to make sure that the git history and archive contents are
-identical.  That this is necessary is a bug in the `3.0 (quilt)'
-format.
+dgit's build functions, and dgit push, should not make any changes to
+your current HEAD.  Sadly this is necessary for packages in the `3.0
+(quilt)' source format.  This is ultimately due to design problems in
+quilt and dpkg-source.

 
 There should be an option which arranges for the `3.0 (quilt)'
 autocommit to not appear on your HEAD, but instead only in the
 
 There should be an option which arranges for the `3.0 (quilt)'
 autocommit to not appear on your HEAD, but instead only in the