1 .TH dgit 1 "" "Debian Project" "dgit"
3 dgit \- git integration with the Debian archive
7 [\fIdgit\-options\fP] \fBclone\fP [\fIdgit\-options\fP]
8 \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdest-dir|\fB/\fP\fIdest-dir]
11 [\fIdgit\-options\fP] \fBfetch\fP|\fBpull\fP [\fIdgit\-options\fP]
15 [\fIdgit\-options\fP] \fBbuild\fP
16 [\fIgit\-buildpackage\-options\fP|\fIdpkg\-buildpackage\-options\fp]
19 [\fIdgit\-options\fP] \fBpush\fP [\fIdgit\-options\fP]
23 treats the Debian archive as a version control system, and
24 bidirectionally gateways between the archive and git. The git view of
25 the package can contain the usual upstream git history, and will be
26 augmented by commits representing uploads done without using dgit.
27 This git history is stored in a canonical location
29 which lives outside the Debian archive.
34 consult the archive and dgit-repos and fetch and/or construct the
35 git view of the history. With clone, the destination directory (by
36 default, the package name in the current directory) will be created,
37 and the new directory's `origin' remote will be set up to point to
38 the package's dgit-repos tree.
43 with some suitable options. Options after
45 will be passed on to git-buildpackage. It is not necessary to
46 use dgit build; it is OK to use any approach which ensures that
47 the generated source package corresponds to the relevant git commit.
48 Tagging and signing should be left to dgit push.
51 does an `upload', pushing the current HEAD to the archive (as a source
52 package) and to dgit-repos (as git commits). This also involves
53 making a signed git tag, and signing the files to be uploaded to the
55 .SH MODEL AND WORKFLOW
56 You may use any suitable git workflow with dgit, provided you
57 satisfy dgit's requirements:
59 dgit maintains what looks a bit like a remote called
61 with one branch per suite. This remote cannot be used with
66 repository for each package contains one ref per suite named
67 \fBdrefs/git/\fR\fIsuite\fR. These should be pushed to only by
68 dgit. They are fast forwarding. Each push on this branch
69 corresponds to an upload (or attempted upload).
71 However, it is perfectly fine to have other branches in dgit-repos;
72 normally the dgit-repos repo for the package will be accessible via
73 the remote name `origin'.
75 dgit push can operate on any commit which is a descendant of the
76 current dgit/suite tip in dgit-repos.
78 Uploads made by dgit contain an additional field
80 in the source package .dsc. (This is added by dgit push.)
81 This specifies a commit (an ancestor of the dgit/suite
82 branch) whose tree is identical to the unpacked source upload.
84 Uploads not made by dgit are represented in git by commits which are
85 synthesised by dgit. The tree of each such commit corresponds to the
86 unpacked source; the single parent is the last known upload - that is,
87 the contents of the dgit/suite branch.
89 dgit expects repos that it works with to have a
91 remote. This refers to the well-known dgit-repos location
92 (currently, the dgit-repos project on Alioth). dgit fetch updates
93 the remote tracking branch for dgit/suite.
97 Go through the motions, fetching all information needed, but do not
98 actually update the output(s). For push, dgit does
99 the required checks and leaves the new .dsc in a temporary file,
100 but does not sign, tag, push or upload.
105 for signing the tag and the upload.
108 does not sign tags or uploads (meaningful only with push).
112 Specifies that we should process source package
114 rather than looking in debian/control. Valid with dgit fetch
118 Spew debugging information to stderr.
121 Specifies a git configuration option. dgit itself is also controlled
122 by git configuration options.
124 .RI \fB--dget=\fR program |\fB--dput=\fR program |\fB--debsign=\fR program
125 Specifies alternative programs to use instead of dget, dput
128 .RI \fB--dget:\fR option |\fB--dput:\fR option |\fB--debsign:\fR option
129 Specifies a single additional option to pass to dget, dput or
130 debsign. Use repeatedly if multiple additional options are required.
133 Specifies the .changes file which is to be uploaded. By default
134 dgit push looks for single .changes file in the parent directory whose
135 filename suggests they it is for the right package and version.
137 dgit looks at the following git config keys to control its behaviour.
138 You may set them with git-config (either in system-global or per-tree
139 configuration), or provide
141 on the dgit command line.
143 .BI dgit-suite. suite .distro
145 .BI dgit.default.distro
147 .BI dgit.default.username
149 .BI dgit-distro. distro .git-url
151 .BI dgit-distro. distro .git-host
153 .BI dgit-distro. distro .git-proto
155 .BI dgit-distro. distro .git-path
157 .BI dgit-distro. distro .git-check
159 .BI dgit-distro. distro .git-create
161 .BI dgit-distro. distro .upload-host
163 .BI dgit-distro. distro .mirror
165 .BI dgit-distro. distro .archive-query
167 .BI dgit-distro. distro .ssh
171 .BR dgit-distro. \fIdistro\fR . *
173 dgit will only work with packages in main. The madison http query API
174 does not give the component.
176 dgit assumes knowledge of the archive layout. There appears to be no
177 sane way to find the path in the archive pool of the .dsc for a
180 Debian Policy needs to be updated to describe the new Vcs-Git-Master
181 field (and to specify that it is an RC bug for that field to refer
182 to an unavailable commit).
184 dgit push should perhaps do `git push origin', or something similar,
187 The mechanism for checking for and creating per-package repos on
188 alioth is a hideous bodge. One consequence is that dgit currently
189 only works for people with push access.
191 Debian Maintainers are currently not able to push, as there is not
192 currently any mechanism for determining and honouring the archive's
193 ideas about access control. Currently only DDs can push.
195 dgit's representation of format `3.0 (quilt)' source packages (even if
196 they were supported) would not represent the patch stack. Currently
197 the patch series representation cannot round trip through the archive.
198 Ideally dgit would represent a quilty package with an origin commit of
199 some kind followed by the patch stack as a series of commits followed
200 by a pseudo-merge (to make the branch fast-forwarding). This would
201 also mean a new `dgit rebase-prep' command or some such to turn such a
202 fast-forwarding branch back into a rebasing patch stack, and a `force'
203 option to dgit push (perhaps enabled automatically) which will make
204 the required pseudo-merge.
206 dgit's handling of .orig.tar.gz is not very sophisticated. Ideally
207 the .orig.tar.gz could be transported via the git repo as git tags.
209 The error messages are often unhelpfully terse and tend to refer to
210 line numbers in dgit.
212 The option parser requires values to be cuddled to the option name.
214 --dry-run often does not work with fetch, even though this is a
215 logically plausible request. (It fails, instead.)