--new is needed for read access to packages in NEW, too. Document this, and make...

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index 38047405cad39f0359a3e393b0956d1b5f6268d4..77d325204d61b1397e4c7fd0c3ff09c1f6b621a3 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -27,7 +27,7 @@ dgit \- git integration with the Debian archive
 [\fIdgit\-opts\fP] \fIaction\fR ...
 .SH DESCRIPTION
 .B dgit
 [\fIdgit\-opts\fP] \fIaction\fR ...
 .SH DESCRIPTION
 .B dgit

-allows you to treats the Debian archive as if it were a git
+allows you to treat the Debian archive as if it were a git

 repository.  See \fBdgit\fP(7) for detailed information about the data
 model, common problems likely to arise with certain kinds of package,
 etc.
 repository.  See \fBdgit\fP(7) for detailed information about the data
 model, common problems likely to arise with certain kinds of package,
 etc.


@@ -96,7 +96,7 @@ into the current branch.
 \fBdgit build\fR ...
 Runs
 .B dpkg-buildpackage
 \fBdgit build\fR ...
 Runs
 .B dpkg-buildpackage

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

 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
 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


@@ -126,7 +126,7 @@ Print a usage summary.
 Constructs the source package, uses
 .B  sbuild
 to do a binary build, and uses mergechanges to merge the source and
 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
+binary changes files.  Options and arguments 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
 passed on to sbuild.  Changes files matching
 .IB package _ version _*.changes
 in the parent directory will be removed; the output is left in


@@ -137,7 +137,7 @@ Tagging, signing and actually uploading should be left to dgit push.
 \fBdgit git-build\fR ...
 Runs
 .B git-buildpackage
 \fBdgit git-build\fR ...
 Runs
 .B git-buildpackage

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

 will be passed on to git-buildpackage.
 
 Tagging, signing and actually uploading should be left to dgit push.
 will be passed on to git-buildpackage.
 
 Tagging, signing and actually uploading should be left to dgit push.


@@ -243,7 +243,11 @@ servers.
 .BI -k keyid
 Use
 .I keyid
 .BI -k keyid
 Use
 .I keyid

-for signing the tag and the upload.
+for signing the tag and the upload.  The default comes from the
+distro's
+.B keyid
+config setting (see CONFIGURATION, below), or failing that, gnupg's
+default.

 .TP
 .BR --no-sign
 does not sign tags or uploads (meaningful only with push).
 .TP
 .BR --no-sign
 does not sign tags or uploads (meaningful only with push).


@@ -278,7 +282,7 @@ This is like
 but it also removes any subdirectories containing different git
 trees (which only unusual packages are likely to create).
 .TP
 but it also removes any subdirectories containing different git
 trees (which only unusual packages are likely to create).
 .TP

-.BR --clean=check " | " -wn
+.BR --clean=check " | " -wc

 Merely check that the tree is clean (does not contain uncommitted
 files), before building a source package.
 .TP
 Merely check that the tree is clean (does not contain uncommitted
 files), before building a source package.
 .TP


@@ -302,8 +306,10 @@ The build-dependencies are not checked (due to
 which violates policy, but may work in practice.
 .TP
 .BR -N " | " --new
 which violates policy, but may work in practice.
 .TP
 .BR -N " | " --new

-The package may be new in this suite.  Without this, dgit will
-refuse to push.
+The package is or may be new in this suite.  Without this, dgit will
+refuse to push.  It may (for Debian, will) be unable to access the git
+history for any packages which have been newly pushed and have not yet
+been published.

 .TP
 .BR --ignore-dirty
 Do not complain if the working tree does not match your git HEAD.
 .TP
 .BR --ignore-dirty
 Do not complain if the working tree does not match your git HEAD.


@@ -342,7 +348,7 @@ as the Debian server will do this automatically when necessary.
 .BR --quilt=linear
 When fixing up source format `3.0 (quilt)' metadata, insist on
 generating a linear patch stack.  If such a stack cannot be generated,
 .BR --quilt=linear
 When fixing up source format `3.0 (quilt)' metadata, insist on
 generating a linear patch stack.  If such a stack cannot be generated,

-fail.
+fail.  This is the default for Debian.

 .TP
 .BR --quilt=auto
 When fixing up source format `3.0 (quilt)' metadata, prefer to
 .TP
 .BR --quilt=auto
 When fixing up source format `3.0 (quilt)' metadata, prefer to


@@ -370,11 +376,11 @@ fixing up, dgit push will fail.
 .TP
 .BI -D
 Prints debugging information to stderr.  Repeating the option produces
 .TP
 .BI -D
 Prints debugging information to stderr.  Repeating the option produces

-more output (currently, up to -DD is meaningfully different).
+more output (currently, up to -DDD is meaningfully different).

 .TP
 .BI -c name = value
 .TP
 .BI -c name = value

-Specifies a git configuration option.  dgit itself is also controlled
-by git configuration options.
+Specifies a git configuration option, to be used for this run.
+dgit itself is also controlled by git configuration options.

 .TP
 .RI \fB-v\fR version "|\fB_\fR | " \fB--since-version=\fR version |\fB_\fR
 Specifies the
 .TP
 .RI \fB-v\fR version "|\fB_\fR | " \fB--since-version=\fR version |\fB_\fR
 Specifies the


@@ -459,7 +465,12 @@ Usually, for passing options to dpkg-genchanges, you should use
 See notes above regarding ssh and dgit.
 
 NB that --gpg:option is not supported (because debsign does not
 See notes above regarding ssh and dgit.
 
 NB that --gpg:option is not supported (because debsign does not

-have that facility).  But see -k.
+have that facility).
+But see
+.B -k
+and the
+.B keyid
+distro config setting.

 .TP
 .BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
 Specifies that the suite to be operated on is part of distro
 .TP
 .BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
 Specifies that the suite to be operated on is part of distro


@@ -478,9 +489,8 @@ 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
 
 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.
+in the archive and in dgit-repos.
+How to set this up is not yet documented.

 .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


@@ -500,7 +510,7 @@ default, in
 .BI --build-products-dir= directory
 Specifies where to find the built files to be uploaded.
 By default, dgit looks in the parent directory
 .BI --build-products-dir= directory
 Specifies where to find the built files to be uploaded.
 By default, dgit looks in the parent directory

-.BR .. ).
+.RB ( .. ).

 .TP
 .BI --existing-package= package
 dgit push needs to canonicalise the suite name.  Sometimes, dgit
 .TP
 .BI --existing-package= package
 dgit push needs to canonicalise the suite name.  Sometimes, dgit


@@ -531,12 +541,14 @@ It is always possible with dgit to clone or fetch a package, make
 changes in git (using git-commit) on the suite branch
 .RB ( "git checkout dgit/" \fIsuite\fR)
 and then dgit push.  You can use whatever gitish techniques you like
 changes in git (using git-commit) on the suite branch
 .RB ( "git checkout dgit/" \fIsuite\fR)
 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
+to construct the commits to push;
+the only requirement is that what you push is a

 descendant of the state of the archive, as provided by dgit in the
 remote tracking branch
 .BR remotes/dgit/dgit/ \fIsuite\fR.
 
 descendant of the state of the archive, as provided by dgit in the
 remote tracking branch
 .BR remotes/dgit/dgit/ \fIsuite\fR.
 

-If you are using dgit to do an NMU, and don't know about the
+If you are using dgit to do an NMU (in Debian),
+and don't know about the

 maintainers' preferred packaging workflows, you should make your
 changes as a linear series of (logicially separated) commits on top of
 what's already in the archive.
 maintainers' preferred packaging workflows, you should make your
 changes as a linear series of (logicially separated) commits on top of
 what's already in the archive.


@@ -565,7 +577,7 @@ branch
 and merge that other commit
 .RB ( "git merge debian/" \fIversion\fR).
 Hopefully this merge will be trivial because the two trees should
 and merge that other commit
 .RB ( "git merge debian/" \fIversion\fR).
 Hopefully this merge will be trivial because the two trees should

-be the same.  The resulting branch head can be merged into your
+be very similar.  The resulting branch head can be merged into your

 working branches
 .RB ( "git checkout master && git merge dgit/" \fIsuite\fR).
 
 working branches
 .RB ( "git checkout master && git merge dgit/" \fIsuite\fR).
 


@@ -599,7 +611,6 @@ Settings likely to be useful for an end user include:
 Specifies the distro for a suite.  dgit keys off the suite name (which
 appears in changelogs etc.), and uses that to determine the distro
 which is involved.  The config used is thereafter that for the distro.
 Specifies the distro for a suite.  dgit keys off the suite name (which
 appears in changelogs etc.), and uses that to determine the distro
 which is involved.  The config used is thereafter that for the distro.

-it then looks

 .TP
 .BI dgit.default.distro " distro"
 The default distro for an unknown suite.
 .TP
 .BI dgit.default.distro " distro"
 The default distro for an unknown suite.


@@ -607,11 +618,13 @@ The default distro for an unknown suite.
 .BR dgit-distro. \fIdistro\fR .readonly " " auto | a " | " true | t | y | 1 " | " false | f | n | 0
 Whether you have push access to the distro.
 For Debian, it is OK to use auto, which uses readonly mode if you are
 .BR dgit-distro. \fIdistro\fR .readonly " " auto | a " | " true | t | y | 1 " | " false | f | n | 0
 Whether you have push access to the distro.
 For Debian, it is OK to use auto, which uses readonly mode if you are

-not pushing right now,
-but setting this to false will avoid relying on the mirror of the dgit
+not pushing right now;
+but, setting this to false will avoid relying on the mirror of the dgit

 git repository server.
 .TP
 .BI dgit-distro. distro .keyid
 git repository server.
 .TP
 .BI dgit-distro. distro .keyid

+See also
+.BR -k .

 .TP
 .BI dgit-distro. distro .mirror " url"
 .TP
 .TP
 .BI dgit-distro. distro .mirror " url"
 .TP