[\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.
but it also removes any subdirectories containing different git
trees (which only unusual packages are likely to create).
.TP
+.BR --clean=check " | " -wn
+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 "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
+.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 " 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-suite. suite .distro
+.BI dgit-distro. distro .keyid
.TP
-.BI dgit.default.distro
+.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 .sshpsql-user
+.BI dgit-distro. distro .madison-distro
+.TP
+.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
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.