path: root/dgit.1
diff options
authorIan Jackson <>2013-08-16 11:31:11 +0100
committerIan Jackson <>2013-08-16 11:31:11 +0100
commit6a783c6b80a9cdd5d744e12637afcd5f10a987ba (patch)
treeb14d13f186f4c75afc4ff14ecffd557b1ea37c2e /dgit.1
parent603475d82ccc0025fa3f1564b8e111b39546288d (diff)
wip doc
Diffstat (limited to 'dgit.1')
1 files changed, 160 insertions, 0 deletions
diff --git a/dgit.1 b/dgit.1
new file mode 100644
index 0000000..6394a16
--- /dev/null
+++ b/dgit.1
@@ -0,0 +1,160 @@
+.TH dgit 1 "" "Debian Project" "dgit"
+dgit \- git integration with the Debian archive
+.B dgit
+[\fIdgit\-options\fP] \fBclone\fP [\fIdgit\-options\fP]
+\fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdest-dir|\fB/\fP\fIdest-dir]
+.B dgit
+[\fIdgit\-options\fP] \fBfetch\fP|\fBpull\fP [\fIdgit\-options\fP]
+.B dgit
+[\fIdgit\-options\fP] \fBbuild\fP
+.B dgit
+[\fIdgit\-options\fP] \fBpush\fP [\fIdgit\-options\fP]
+.B dgit
+treats the Debian archive as a version control system, and
+bidirectionally gateways between the archive and git. The git view of
+the package can contain the usual upstream git history, and will be
+augmented by commits representing uploads done without using dgit.
+This git history is stored in a canonical location
+.B dgit-repos
+which lives outside the Debian archive.
+.B dgit clone
+.B dgit fetch
+consult the archive and dgit-repos and fetch and/or construct the
+git view of the history. With clone, the destination directory (by
+default, the package name in the current directory) will be created.
+.B dgit build
+.B git-buildpackage
+with some suitable options. Options after
+.B build
+will be passed on to git-buildpackage. It is not necessary to
+use dgit build; it is OK to use any approach which ensures that
+the generated source package corresponds to the relevant git commit.
+Tagging and signing should be left to dgit push.
+.B dgit push
+does an "upload", pushing the current HEAD to the archive (as a source
+package) and to dgit-repos (as git commits). This also involves
+making a signed git tag, and signing the files to be uploaded to the
+You may use any suitable git workflow with dgit, provided you
+satisfy dgit's requirements:
+.B dgit-repos
+repository for each package contains one branch per suite named
+\fBdgit/\fR\fIsuite\fR. These should be pushed to only by
+dgit. They are fast forwarding. Each push on this branch
+corresponds to an upload (or attempted upload).
+dgit push can operate on any commit which is a descendant of the
+current dgit/suite tip in dgit-repos.
+Uploads made by dgit contain an additional field
+.B Vcs-Git-Master
+in the source package .dsc. (This is added by dgit push.)
+This specifies a commit (an ancestor of the dgit/suite
+branch) whose tree is identical to the unpacked source upload.
+Uploads not made by dgit are represented in git by commits which are
+synthesised by dgit. The tree of each such commit corresponds to the
+unpacked source; the single parent is the last known upload - that is,
+the contents of the dgit/suite branch.
+dgit expects repos that it works with to have a
+.B dgit
+remote. This refers to the well-known dgit-repos location
+(currently, the dgit-repos project on Alioth). dgit fetch updates
+the remote tracking branch for dgit/suite.
+.BR --dry-run | -n
+Go through the motions, fetching all information needed, but do not
+actually update the output(s). For fetch and pull, dgit determines
+which git commit corresponds to the archive but does not update
+remotes/dgit/dgit/suite or do any merge. For push, dgit does
+the required checks and leaves the new .dsc in a temporary file,
+but does not sign, tag, push or upload.
+.BI -k keyid
+.I keyid
+for signing the tag and the upload.
+.BR --no-sign
+does not sign tags or uploads (meaningful only with push).
+.BI -D
+Spew debugging information to stderr.
+.BI -c name = value
+Specifies a git configuration option. dgit itself is also controlled
+by git configuration options.
+.RI \fB--dget=\fR program |\fB--dput=\fR program |\fB--debsign=\fR program
+Specifies alternative programs to use instead of dget, dput
+or debsign.
+.RI \fB--dget:\fR option |\fB--dput:\fR option |\fB--debsign:\fR option
+Specifies a single additional option to pass to dget, dput or
+debsign. Use repeatedly if multiple additional options are required.
+.BI -C changesfile
+Specifies the .changes file which is to be uploaded. By default
+dgit push looks for single .changes file in the parent directory whose
+filename suggests they it is for the right package and version.
+dgit currently only works with Format 1.0 packages.
+dgit is not nearly configurable enough. The locations for dgit-repos
+(on alioth) and for the Debian archive are currently hardcoded.
+There is not yet any support for suites which are in different
+distributions to Debian.
+dgit will only work with packages in main. The madison http query API
+does not give the component.
+dgit assumes knowledge of the archive layout. There appears to be no
+sane way to find the path in the archive pool of the .dsc for a
+particular suite.
+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 representation of Format 3.0 (quilt) source packages (even if
+they were supported) would not represent the patch stack. Currently
+the patch series representation cannot round trip through the archive.
+Ideally dgit would represent a quilty package with an origin commit of
+some kind followed by the patch stack as a series of commits followed
+by a pseudo-merge (to make the branch fast-forwarding). This would
+also mean a new "dgit rebase-prep" command or some such to turn such a
+fast-forwarding branch back into a rebasing patch stack, and a "force"
+option to dgit push (perhaps enabled automatically) which will make
+the required pseudo-merge.
+dgit's handling of .orig.tar.gz is not very sophisticated. Ideally
+the .orig.tar.gz could be transported via the git repo as git tags.
+The error messages are often unhelpfully terse and tend to refer to
+line numbers in dgit.
+The option parser requires values to be cuddled to the option name.