[\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.
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]
\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
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
\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.
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
.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).
--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 " | " -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
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.
+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.
.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
.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
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
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
.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
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.
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).
.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.
.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
+See also
+.BR -k .
+.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.
-
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.
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.
~ianmdlvl / dgit.git / blobdiff