The usual workflow is:
.br
-1. dgit clone or fetch
+1. \fBdgit clone\fR or \fBfetch\fR;
.br
-2. make, dev test and commit changes in git as desired
+2. make, do dev tests, and commit changes in git as desired;
.br
-3. run dgit build, dgit sbuild or
-dgit build-source, or generate the source and binary packages for upload
-some other way
+3. build packages for upload, using e.g. \fBdgit sbuild\fR
.br
-4. do pre-upload tests of the proposed upload
+4. do pre-upload tests of the proposed upload;
.br
-5. dgit push.
+5. \fBdgit push\fR.
.SH OPERATIONS
.TP
\fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
the invocation host. The build-host needs gnupg installed, with your
public key in its keyring (but not your private key, obviously).
.TP
+.B dgit setup-mergechangelogs
+Configures a git merge helper for the file
+.B debian/changelog
+which uses
+.BR dpkg-mergechangelogs .
+You can use this in any git repository, not just ones used with
+the other dgit operations.
+.TP
.B dgit quilt-fixup
`3.0 (quilt)' format source packages need changes representing not
only in-tree but also as patches in debian/patches. dgit quilt-fixup
--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
+with one of the build options, using
+.BR "git clean -xdff" .
+This is like
+"git clean -xdf"
+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
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 "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-suite. suite .distro
+.BI dgit.default.distro " distro"
+The default distro for an unknown suite.
.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
+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 .sshpsql-host
+.BI dgit-distro. distro .archive-query-default-component
+.TP
+.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
-We should be using some kind of vhost/vpath setup for the git repos on
-alioth, so that they can be moved later if and when this turns out to
-be a good idea.
-
-dgit push should perhaps do `git push origin', or something similar,
-by default.
-
-Debian does not have a working rmadison server, so to find out what
-version of a package is in the archive, or to canonicalise suite
-names, we ssh directly into the ftpmaster server and run psql there to
-access the database.
-
-The mechanism for checking for and creating per-package repos on
-alioth is a hideous bodge. One consequence is that dgit currently
-only works for people with push access.
-
-Debian Maintainers are currently not able to push, as there is not
-currently any mechanism for determining and honouring the archive's
-ideas about access control. Currently only DDs can push.
+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
The option parser requires values to be cuddled to the option name.
-dgit assumes knowledge of the archive database. (The information dgit
-needs is not currently available via any public online service with a
-well-defined interface, let alone a secure one.)
-
--dry-run does not always work properly, as not doing some of the git
fetches may result in subsequent actions being different. Doing a
non-dry-run dgit fetch first will help.