3 dgit-user - making and sharing changes to Debian packages, with git
7 dgit lets you fetch the source code to every package on your
9 as if your distro used git to maintain all of it.
12 build updated binary packages (.debs)
13 and install and run them.
14 You can also share your work with others.
16 This tutorial gives some recipes and hints for this.
17 It assumes you have basic familiarity with git.
18 It does not assume any initial familiarity with
19 Debian's packaging processes.
21 If you are a package maintainer within Debian; a DM or DD;
23 this tutorial is not for you.
24 Try L<dgit-nmu-simple(7)>, L<dgit-maint-*(7)>,
25 or L<dgit(1)> and L<dgit(7)>.
29 (These runes will be discussed later.)
33 % dgit clone glibc jessie,-security
35 % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
36 % git commit -a -m 'Fix libc lost output bug'
37 % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
38 % sudo apt-get build-dep glibc
39 % dpkg-buildpackage -uc -b
40 % sudo dpkg -i ../libc6_*.deb
58 % dgit pull jessie,-security
59 % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
60 % dpkg-buildpackage -uc -b
61 % sudo dpkg -i ../libc6_*.deb
65 =head1 FINDING THE RIGHT SOURCE CODE - DGIT CLONE
69 % dgit clone glibc jessie,-security
74 dgit clone needs to be told the source package name
75 (which might be different to the binary package name,
76 which was the name you passed to "apt-get install")
77 and the codename or alias of the Debian release
78 (this is called the "suite").
80 =head2 Finding the source package name
82 For many packages, the source package name is obvious.
83 Otherwise, if you know a file that's in the package,
84 you can look it up with dpkg:
88 % dpkg -S /lib/i386-linux-gnu/libc.so.6
89 libc6:i386: /lib/i386-linux-gnu/libc.so.6
92 Status: install ok installed
99 libc6 is a "multi-arch: allowed" package,
100 which means that it exists in several different builds
101 for different architectures.
102 That's where C<:i386> comes from.)
104 =head2 Finding the Debian release (the "suite")
107 Debian (and derived) distros normally refer to their releases by codenames.
108 Debian also has aliases which refer to the current stable release etc.
109 So for example, at the time of writing
110 Debian C<jessie> (Debian 8) is Debian C<stable>; and
111 the current version of Ubuntu is C<yakkety> (Yakkety Yak, 16.10).
112 You can specify either
113 the codename C<jessie> or the alias C<stable>.
114 If you don't say, you get C<sid>,
115 which is Debian C<unstable> - the main work-in progress branch.
117 If you don't know what you're running, try this:
121 % grep '^deb' /etc/apt/sources.list
122 deb http://the.earth.li/debian/ jessie main non-free contrib
128 For Debian, you should add C<,-security>
129 to the end of the suite name.
130 Hence, in our example
131 C<jessie> becomes C<jessie,-security>.
134 =head1 WHAT DGIT CLONE PRODUCES
136 =head2 What branches are there
138 dgit clone will give you a new working tree,
139 and arrange for you to be on a branch named like
140 C<dgit/jessie,-security> (yes, with a comma in the branch name).
142 For each release (like C<jessie>)
143 there is a tracking branch for the contents of the archive, called
144 C<remotes/dgit/dgit/jessie>
145 (and similarly for other suites). This can be updated with
146 C<dgit fetch jessie>.
147 This, the I<remote suite branch>,
148 is synthesized by your local copy of dgit.
149 It is fast forwarding.
151 Debian separates out the security updates, into C<debian-security>.
152 Telling dgit C<debian,-security> means that it should include
153 any updates available in C<debian-security>.
155 (You can also dgit fetch in a tree that wasn't made by dgit clone.
156 If there's no C<debian/changelog>
157 you'll have to supply a C<-p>I<package> option to dgit fetch.)
159 =head2 What kind of source tree do you get
161 If the Debian package is based on some upstream release,
162 the code layout should be like the upstream version.
163 You should find C<git grep> helpful to find where to edit.
165 The package's Debian metadata and the scripts for building binary
166 packages are under C<debian/>.
167 C<debian/control>, C<debian/changelog> and C<debian/rules> are the
169 The Debian Policy Manual has most of the in-depth
172 For many Debian packages,
173 there will also be some things in C<debian/patches/>.
174 It is best to ignore these.
175 Insofar as they are relevant
176 the changes there will have been applied to the actual files,
177 probably by means of actual comments in the git history.
178 The contents of debian/patches are ignored
179 when building binaries
180 from dgitish git branches.
182 (For Debian afficionados:
183 the git trees that come out of dgit are
184 "patches-applied packaging branches
185 without a .pc directory".)
187 =head2 What kind of history you get
189 If you're lucky, the history will be a version of,
191 the Debian maintainer's own git history,
192 or upstream's git history.
194 But for many packages the real git history
196 or has not been published in a dgitish form.
197 So yuu may find that the history is a rather short
198 history invented by dgit.
200 dgit histories often contain automatically-generated commits,
201 including commits which make no changes but just serve
202 to make a rebasing branch fast-forward.
203 This is particularly true of
204 combining branches like
207 If the package maintainer is using git then
209 you may find that there is a useful C<vcs-git> remote
210 referring to the Debian package maintainer's repository
212 You can see what's there with C<git fetch vcs-git>.
213 But use what you find there with care:
214 Debian maintainers' git repositories often have
215 contents which are very confusing and idiosyncratic.
216 In particular, you may need to manually apply the patches
217 that are in debian/patches before you do anything else!
221 =head2 Always commit before building
225 % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
226 % git commit -a -m 'Fix libc lost output bug'
230 Debian package builds are often quite messy:
231 they may modify files which are also committed to git,
232 or leave outputs and teporary files not covered by C<.gitignore>.
234 Kf you always commit,
244 to tidy up after a build.
245 (If you forgot to commit, don't use those commands;
246 instead, you may find that you can use C<git add -p>
247 to help commit what you actually wanted to keep.)
249 These are destructive commands which delete all new files
250 (so you B<must> remember to say C<git add>)
251 and throw away edits to every file
252 (so you B<must> remember to commit).
254 =head2 Update the changelog (at least once) before building
258 % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
262 The binaries you build will have a version number which ultimately
263 comes from the C<debian/changelog>.
264 You want to be able to tell your
265 binaries apart from your distro's.
267 So you should update C<debian/changelog>
268 to add a new stanza at the top,
271 This rune provides an easy way to do this.
272 It adds a new changelog
273 entry with an uninformative message and a plausible version number
274 (containing a bit of your git commit id).
276 If you want to be more sophisticated,
277 the package C<dpkg-dev-el> has a good Emacs mode
278 for editing changelogs.
279 Alternatively, you could edit the changelog with another text editor,
280 or run C<dch> or C<gbp dch> with different options.
281 Choosing a good version number is slightly tricky and
282 a complete treatment is beyond the scope of this tutorial.
284 =head2 Actually building
288 % sudo apt-get build-dep glibc
289 % dpkg-buildpackage -uc -b
293 apt-get build-dep installs the build dependencies according to the
294 official package, not your modified one. So if you've changed the
295 build dependencies you might have to install some of them by hand.
297 dpkg-buildpackage is the primary tool for building a Debian source
299 C<-uc> means not to pgp-sign the results.
300 C<-b> means build all binary packages,
301 but not to build a source package.
305 =head2 Debian Jessie or older
309 % sudo dpkg -i ../libc6_*.deb
313 You can use C<dpkg -i> to install the
314 .debs that came out of your package.
316 If the dependencies aren't installed,
317 you will get an error, which can usually be fixed with
318 C<apt-get -f install>.
320 =head2 Debian Stretch or newer
324 % sudo apt install ../libc6_*.deb
330 If you're working on a library package and your system has multiple
331 architectures enabled,
332 you may see something like this:
336 dpkg: error processing package libpcre3-dev:amd64 (--configure):
337 package libpcre3-dev:amd64 2:8.39-3~3.gbp8f25f5 cannot be configured because libpcre3-dev:i386 is at a different version (2:8.39-2)
341 The multiarch system used by Debian requires each package which is
342 present for multiple architectures to be exactly the same across
343 all the architectures for which it is installed.
346 is to build the package for all the architectures you
348 You'll need a chroot for each of the secondary architectures.
349 This iw somewhat tiresome,
350 even though Debian has excellent tools for managing chroots.
351 C<sbuild-createchroot> from the sbuild package is a
354 Otherwise you could deinstall the packages of interest
355 for those other architectures
356 with something like C<dpkg --remove libpcre3:i386>.
358 If neither of those are an option,
359 your desperate last resort is to try
360 using the same version number
361 as the official package for your own package.
362 (The verseion is controlled by C<debian/changelog> - see above,)
363 This is not ideal because it makes it hard to tell what is installed,
364 because it will mislead and confuse apt.
366 With the "same number" approach you may still get errors like
370 trying to overwrite shared '/usr/include/pcreposix.h', which is different from other instances of package libpcre3-dev
374 but passing C<--force-overwrite> to dpkg will help
375 - assuming you know what you're doing.
377 =head1 SHARING YOUR WORK
379 The C<dgit/jessie,-security> branch (or whatever) is a normal git branch.
380 You can use C<git push> to publish it on any suitable git server.
382 Anyone who gets that git branch from you
383 will be able to build binary packages (.deb)
386 If you want to contribute your changes back to Debian,
387 you should probably send them as attachments to
389 L<Debian Bug System|https://bugs.debian.org/>
390 (either a followup to an existing bug, or a new bug).
391 Patches in C<git-format-patch> format are usually very welcome.
393 =head2 Source packages
396 git branch is not sufficient to build a source package
398 Source packages are somewhat awkward to work with.
399 Indeed many plausible git histories or git trees
400 cannot be converted into a suitable source package.
401 So I recommend you share your git branch instead.
403 If a git branch is not enough, and
404 you need to provide a source package
405 but don't care about its format/layout
406 (for example because some software you have consumes source packages,
408 you can use this recipe to generate a C<3.0 (native)>
409 source package, which is just a tarball
410 with accompanying .dsc metadata file:
414 % echo '3.0 (native)' >debian/source/format
415 % git commit -m 'switch to native source format' debian/source/format
416 % dgit -wgf build-source
420 If you need to provide a good-looking source package,
421 be prepared for a lot more work.
422 You will need to read much more, perhaps starting with
423 L<dgit-nmu-simple(7)>,
424 L<dgit-sponsorship(7)> or