Improve manpage comment about defining a new distro.

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index 2d06fd999f9347d85bdb6e3047ee8156de8f4e69..4dfc6d2f8df9863d130a9814881d2aa17cf9beb1 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


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


@@ -357,11 +370,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


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


@@ -574,49 +586,82 @@ Then run
 .BR "dgit push"
 to actually upload the result.
 .SH CONFIGURATION
 .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.
 configuration), or provide
 .BI -c key = value
 on the dgit command line.

+.LP
+Settings likely to be useful for an end user include:
+.TP
+.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
 .TP

-.BI dgit-suite. suite .distro
+.BI dgit.default.distro " distro"
+The default distro for an unknown suite.

 .TP
 .TP

-.BI dgit.default.distro
+.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
 .TP
 .BI dgit-distro. distro .username

+Not relevant for Debian.

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

-.BI dgit-distro. distro .git-user
+.BI dgit-distro. distro .git-url

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

-.BI dgit-distro. distro .git-create
+.BI dgit-distro. distro .git-check-suffix

 .TP
 .TP

-.BI dgit-distro. distro .upload-host
+.BR dgit-distro. \fIdistro\fR .diverts.divert " " new-distro | / \fIdistro-suffix\fR

 .TP
 .TP

-.BI dgit-distro. distro .mirror
+.BI dgit-distro. distro .git-create " " ssh-cmd | true

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

-.BI dgit-distro. distro .archive-query-default-component
+.BR dgit-distro. \fIdistro\fR .archive-query- ( url | tls-key | curl-ca-args )

 .TP
 .TP

-.BI dgit-distro. distro .sshpsql-user
+.BI dgit-distro. distro .madison-distro

 .TP
 .TP

-.BI dgit-distro. distro .sshpsql-host
+.BI dgit-distro. distro .archive-query-default-component
+.TP
+.BI dgit-distro. distro .ssh

 .TP
 .BI dgit-distro. distro .sshpsql-dbname
 .TP
 .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
 .TP

-.BI dgit-distro. distro .keyid
+.BI dgit-distro. distro .backports-quirk

 .TP
 .BR dgit.default. *
 for each
 .TP
 .BR dgit.default. *
 for each


@@ -637,9 +682,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
 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.
 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.