5 Hi. I'm here to plug dgit, which is a system for treating the Debian
6 archive like a git remote.
8 I'm going to talk for about 35 minutess and then I'll take questions.
11 When we work on Debian we take on different roles. The biggest
12 difference is between the maintainer (or maintainers) of a package,
13 working on their own package, and everyone else.
15 I'm going to start by presenting dgit from the point of view of
16 everyone else: NMUers, sponsorship, bug squashers, downstreams,
17 users, teams doing cross-archive work
18 like transitions and reproducible builds, and so on. Maintainers,
19 please be patient - I'll get to you later
24 The point of dgit is that it lets everyone treat the archive as if it
25 were a git repository.
27 You can dgit clone any package, in any suite (so, for example, sid or
28 experimental) and you will get a git tree which is exactly the same as
31 So dgit always works the same, from the non-maintainer's point of
32 view, on any package: the operation is completely uniform. You don't
33 need to know anything about the maintainer's verson control workflow
34 tools or source format preferences.
36 You can then work on the package in git, the way you would work in git
37 with any other project. In particular, you can:
40 * cherry pick changes from other branches
41 * git reset, git clean
42 * git rebase -i to polish a more complex set of changes into
44 * all the other usual gitish stuff
46 If you have the right authority you can also dgit push, to upload.
47 That is, a DD can dgit push any package; a DM can dgit push the
48 packages that the archive thinks they can upload.
50 Before you push you still have to do a build. dgit does not replace
51 existing ways of building source and binary packages, although it does
52 provide some helpful build rune wrappers (more about that later).
55 If you don't want to, or can't, upload to Debian, but do want so share
56 your work with other people, you can git push your dgit
57 branch anywhere suitable, so they can fetch it. So, for example, you
58 could share your branch with your sponsor, who could then approve it
59 by running dgit push. dgit's branches are ordinary git branches for
66 Behind the scenes, dgit works by providing a set of git repositories
67 in parallel to the existing archive.
69 Every dgit push is actually two underlying operations: the first is a
70 git tag and push, to the dgit git server. The second is a
71 conventional package upload - with a wrinkle: the .dsc of an upload
72 done with dgit contains xxxfld the git commit hash that was pushed.
74 Likewise, fetch and clone combine information from the archive and the
75 git history. If the most recent upload was done with dgit, the commit
76 hash in the dsc enables dgit fetch to find the right commit and
77 present it to you. If the most recent upload was not done with dgit,
78 dgit imports the source package into git - and stitches it into the
79 existing dgit history, if there is one.
81 You do need to treat dgit git branches a bit specially is if you need to build
82 source pacakges (for upload, for example). In this case dgit needs
83 the .orig tarballs for your source package. If you are not doing a
84 new upstream version, dgit fetch will get the relevant .origs for you.
85 If you are dnxxx, then presumably you have obtained them as part of
86 preparing your package, or you can build them easily.
89 ==== NMU linear history slide
91 As a general rule, the dgit history structure should be up to the
92 maintainer - at least, if they care.
94 If you are doing a straightforward NMU you should produce a
95 well-structured linear sequence of commits, as you would for any other
96 git upstream. Not only does this mean that if the maintainer is using
97 dgit, they can hopefully easily include your changes; it also means
98 that if they _aren't_ using dgit, at least you have published a
99 history which is suitable for rebasing onto theirs, or whatever.
101 If the source package is `3.0 (quilt)', you shouldn't touch
102 debian/patches; dgit will take care of that for you. This is the
103 other reason why you should provide a tidy linear patch series: if the
104 maintainer likes quilt and is not using dgit, your changes will be
105 automatically presented to them in a fairly plausible format like they
108 An ordinary NMUer should not normally update a patch in the quilt
109 stack directly. Ie, an NMUer shouldn't squash their changes into an
110 existing patch. This is because while it's easy for the maintainer to
111 squash it themselves, if they want, it's a little harder for the
112 maintainer to disentangle a squashed patch. This can also result in
113 people having to read interdiffs, which are notoriously confusing.
116 ==== NMU linear history on top of basic dgit history
118 Sadly, unless the maintainer uses dgit, the history you see in dgit
119 will not be the maintainer's history.
121 This is because maintainers' git branches often differ from the source
122 packages in the archive.
124 If you dgit clone a package and it has an X-Vcs-Git header, dgit will
125 set up a remote for it, so you can fetch the history and use it if you
126 like. So in that sense dgit clone encompasses debcheckout.
128 But, in the general case, the X-Vcs-Git tree may not be immediately
129 useable to someone not familiar with the package.
131 The maintainer's repo might contain only a debian/ directory, or be a
132 quilty tree without patches applied. And the tag and suite naming
133 conventions can vary too. So while the maintainer's history can be
134 useful if you want to do archeaology, it's not in general suitable for
137 There is also the problem that the maintainer's nominated git server
138 might be anywhere, so it might be down, or gone away, or compromised.
141 So, if the maintainer is not using dgit, dgit has to synthesise a git
142 history. The history you see in dgit will then have a very basic
143 branch and commit structure, rather than representing the package's
147 Which brings me onto the other side of this talk: dgit for
150 ==== history comparison slide
152 For the reasons I've explained, downstream dgit users would like you
153 as a maintainer to use dgit push to do your uploads. They will then
154 be able to see, and directly work with, your own history.
156 In general, the point of using a dvcs like git is to publish your
157 work. The existing ways of publishing git histories for Debian
158 packagess aren't uniformly useable for users: they require the user to
159 understand the maintainer's git working practices.
161 What dgit does is provide a way for you to publish a history which
162 users can rely on actually corresponding to the archive, and use
163 immediately without special knowledge.
165 But it's in your own selfish interest to upload with dgit, too:
167 If you use dgit, you will be able to directly merge NMUs, patches
168 proposed via pull-request emails, and so on: Because, in this case,
169 the dgit-using contributor will have based their work on your own
170 history. Whereas, if you don't, dgit-using contributors will be
171 working on a stub history, and may dgit push commits based on that
172 stub. You can dgit fetch it even if you're not using dgit for your
173 uploads, but when you do at the very least you'll have to rebase the
176 Another advantage of using dgit for your maintainer uploads is that it
177 will put your own history on browse.dgit.debian.org, rather than
178 advertising dgit's stub history (which can also be out of date).
180 If you use dgit push, you get an extra check that the source package
181 you are uploading is exactly the same as your git HEAD. This can
182 save you some dsc-based checks.
184 And, of course, as I say, doing your uploads with dgit will improve
185 downstream dgit users' lives.
190 dgit is not a replacement for existing git packaging tools; it's
191 intended to complement them. So (unlike git-dpm) dgit does not define
192 a git history structure.
194 Nor does dgit define a branch structure distinguishing upstream or
195 downstream branches, pristine tar branches, etc.
197 dgit doesn't require a particular source format; it couldn't, since it
198 needs to work with any package.
201 ==== data flow slide with EQUAL and FF
203 dgit push imposes only two requirements on your git trees, which stem
204 directly from dgit's objectives.
206 The most important requirement is that your git tree is identical to
207 the unpacked source package. (Technically, in the case of a `3.0
208 (quilt)' package, it is what is sometimes called a `patches-applied
209 packaging branch without .pc directory' xxx.)
211 For all native packages, and for users of git-dpm and raw git, this is
212 already the interchange format. These maintainers can start using
213 dgit right away. Please do!
215 For those using git-buildpackage with `3.0 (quilt)', things are a bit
216 more complicated. I'm told that gbp pq can be used to generate a
217 patches-applied branch, and that some users prefer to use that as the
218 interchange git branch, but I know this is far from universal. I'm
219 talking to the git-buildpackage maintainers about gbp integration, so
224 The other requirement of dgit is simply that the dgit branches are
225 fast-forwarding. So if your tools have made a rebasing branch, you
226 may need to make a fake merge (with git merge -s ours) before pushing.
227 I'm intending to provide some rather more cooked way to do this but I
228 haven't decided the exact shape yet.
233 There are a few other things I ought to cover, since they often come
234 up. They're are relevant to maintainers and non-maintainers:
237 DMs currently need to email me a signed copy of their ssh key, in
238 order to be able to push. This is because the dgit repo server uses
239 ssh as a transport and the project doesn't, right now, have a record
243 The dgit git history does not generally include the package upload
244 history. git-import-dscs can produce a git branch representing the
245 upload history, but dgit doesn't run that itself. why noy xxx
247 One could push such a branch to the archive with dgit push. But, it
248 seems to me that the git history structure ought to up to the
249 maintainer, and if the maintainer chooses to use dgit, the
250 maintainers's existing git history is probably better.
253 It is normally best to use one of dgit's build operations to build for
254 upload. This is mainly because most other tools remove .gitignore by
255 default. dgit requires that the source package and git tree are the
256 same, so if your git tree has .gitignore in it, your source package
262 Many packages have strangely-behaved or plain buggy clean targets.
263 Because dgit knows that your git tree is canonical, it can help work
264 around this: you can tell dgit to use git-clean instead, avoiding the
265 package's clean target entirely.
267 If you're not in the habit of forgetting to say git-add, you can set a
268 configuration option to have dgit always use git-clean. Then you will
269 never have to fight a buggy clean target, in a strange package, ever again.
274 Some source packages contain files not in the maintainers' git
275 branches, and which are needed to build: most commonly, autotools
276 output. Such git branches are not useable with dgit.
278 But nowadays most people recommend that the package build should
279 always rerun autotools. If you do that, then neither your git tree
280 nor your source package need contain the autotools output and all is
283 Alternatively, you can commit the autotools output to git. Merge
284 conflicts etc. are easily resolved by rerunning autotools.
287 ==== Future plans slide
289 I have a number of plans for the future, some of which I need help
290 with. But I don't have time, I'm afraid, to go through them.
292 Instead, I'm going to open the talk up to questions now.