X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=8ddab7a74211295603af73b5c78dc30930ecf0b3;hp=c569347e658bb6480e12072b0985c5dcef4670e1;hb=68a8f001e52757fa9b5ae3289eaf1e6a8dc65512;hpb=8ee9e3edb66cb7af5aab96e44a2cfa0ff84b529a

diff --git a/dgit.1 b/dgit.1
index c569347e..8ddab7a7 100644
--- 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
-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.
@@ -96,7 +96,7 @@ into the current branch.
 \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
@@ -267,7 +267,7 @@ from being run.
 
 --clean=git is useful when the package's clean target is troublesome;
 the downside is simply that git clean may delete files you forgot to
-git add.
+git add.  --clean=git can also avoid needing the build-dependencies.
 .TP
 .BR --clean=git-ff " | " -wgf
 The source tree should be cleaned, before building a source package
@@ -278,6 +278,10 @@ This is like
 but it also removes any subdirectories containing different git
 trees (which only unusual packages are likely to create).
 .TP
+.BR --clean=check " | " -wc
+Merely check that the tree is clean (does not contain uncommitted
+files), before building a source package.
+.TP
 .BR --clean=none " | " -wn
 Do not clean the tree before building a source package.  If there are
 files which are not in git, or if the build creates such files, a
@@ -288,6 +292,15 @@ Use dpkg-buildpackage to do the clean, 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 --clean=dpkg-source-d " | " -wdd
+Use
+.B dpkg-buildpackage -d
+to do the clean, so that the source package
+is cleaned by dpkg-source running the package's clean target.
+The build-dependencies are not checked (due to
+.BR -d ),
+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.
@@ -329,7 +342,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,
-fail.
+fail.  This is the default for Debian.
 .TP
 .BR --quilt=auto
 When fixing up source format `3.0 (quilt)' metadata, prefer to
@@ -357,11 +370,11 @@ fixing up, dgit push will fail.
 .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
-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
@@ -465,9 +478,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
-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
@@ -487,7 +499,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
-.BR .. ).
+.RB ( .. ).
 .TP
 .BI --existing-package= package
 dgit push needs to canonicalise the suite name.  Sometimes, dgit
@@ -518,12 +530,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
-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.
 
-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.
@@ -574,49 +588,82 @@ Then run
 .BR "dgit push"
 to actually upload the result.
 .SH CONFIGURATION
-dgit looks at the following git config keys to control its behaviour.
-You may set them with git-config (either in system-global or per-tree
+dgit can be configured via the git config system.
+You may set keys with git-config (either in system-global or per-tree
 configuration), or provide
 .BI -c key = value
 on the dgit command line.
+.LP
+Settings likely to be useful for an end user include:
 .TP
-.BI dgit-suite. suite .distro
+.BR dgit-suite. \fIsuite\fR .distro " \fIdistro\fR"
+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
+.BI dgit.default.distro " distro"
+The default distro for an unknown suite.
+.TP
+.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
+git repository server.
+.TP
+.BI dgit-distro. distro .keyid
+.TP
+.BI dgit-distro. distro .mirror " url"
 .TP
 .BI dgit-distro. distro .username
+Not relevant for Debian.
 .TP
-.BI dgit-distro. distro .git-url
+.BI dgit-distro. distro .upload-host
+Might be useful if you have an intermediate queue server.
+.SH ACCESS CONFIGURATION
+There are many other settings which specify how a particular distro's
+services (archive and git) are provided.  These should not normally be
+adjusted, but are documented for the benefit of distros who wish to
+adopt dgit.
+.TP
+.BR dgit-distro. \fIdistro\fR /push. *
+If set, overrides corresponding non \fB/push\fR config when
+.BR readonly=false ,
+or when pushing and
+.BR readonly=auto .
 .TP
-.BI dgit-distro. distro .git-user
+.BI dgit-distro. distro .git-url
 .TP
-.BI dgit-distro. distro .git-host
+.BR dgit-distro. \fIdistro\fR .git-url [ -suffix ]
 .TP
 .BI dgit-distro. distro .git-proto
 .TP
 .BI dgit-distro. distro .git-path
 .TP
-.BI dgit-distro. distro .git-check
+.BR dgit-distro. \fIdistro\fR .git-check " " true | false | url | ssh-cmd
 .TP
-.BI dgit-distro. distro .git-create
+.BI dgit-distro. distro .git-check-suffix
 .TP
-.BI dgit-distro. distro .upload-host
+.BR dgit-distro. \fIdistro\fR .diverts.divert " " new-distro | / \fIdistro-suffix\fR
 .TP
-.BI dgit-distro. distro .mirror
+.BI dgit-distro. distro .git-create " " ssh-cmd | true
 .TP
-.BI dgit-distro. distro .archive-query
+.BR dgit-distro. \fIdistro\fR .archive-query " " ftpmasterapi: " | " madison: "\fIdistro\fR | " dummycat: "\fI/path\fR  | " sshpsql: \fIuser\fR @ \fIhost\fR : \fIdbname\fR
 .TP
-.BI dgit-distro. distro .archive-query-default-component
+.BR dgit-distro. \fIdistro\fR .archive-query- ( url | tls-key | curl-ca-args )
+.TP
+.BI dgit-distro. distro .madison-distro
 .TP
-.BI dgit-distro. distro .sshpsql-user
+.BI dgit-distro. distro .archive-query-default-component
 .TP
-.BI dgit-distro. distro .sshpsql-host
+.BI dgit-distro. distro .ssh
 .TP
 .BI dgit-distro. distro .sshpsql-dbname
 .TP
-.BI dgit-distro. distro .ssh
+.BR dgit-distro. \fIdistro\fR . ( git | sshpsql ) - ( user | host | user-force )
 .TP
-.BI dgit-distro. distro .keyid
+.BI dgit-distro. distro .backports-quirk
 .TP
 .BR dgit.default. *
 for each
@@ -637,9 +684,6 @@ and other subprograms and modules used by dgit are affected by various
 environment variables.  Consult the documentaton for those programs
 for details.
 .SH BUGS
-Debian Maintainers are currently not able to push, as the project
-lacks a list of their ssh keys (!)
-
 dgit's git representation of format `3.0 (quilt)' source packages does
 not represent the patch stack as git commits.  Currently the patch
 series representation cannot round trip between git and the archive.