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
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
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
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
74 dgit clone needs to be told the source package name
75 (which might be different to the binary package name)
76 and the codename or alias of the Debian release
77 (this is called the "suite").
79 =head2 Finding the source package name
81 For many packages, the source package name is obvious.
82 Otherwise, if you know a file that's in the package,
83 you can look it up with dpkg:
87 % dpkg -S /lib/i386-linux-gnu/libc.so.6
88 libc6:i386: /lib/i386-linux-gnu/libc.so.6
91 Status: install ok installed
98 libc6 is a "multi-arch: allowed" package,
99 which means that it exists in several different builds
100 for different architectures.
101 That's where C<:i386> comes from.)
103 =head2 Finding the Debian release (the "suite")
106 Debian (and derived) distros normally refer to their releases by codenames.
107 Debian also has aliases which refer to the current stable release etc.
108 So for example, at the time of writing
109 Debian C<jessie> (Debian 8) is Debian C<stable>; and
110 the current version of Ubuntu is C<yakkety> (Yakkety Yak, 16.10).
111 You can specify either
112 the codename C<jessie> or the alias C<stable>.
113 If you don't say, you get C<sid>,
114 which is Debian C<unstable> - the main work-in progress branch.
116 If you don't know what you're running, try this:
120 % grep '^deb' /etc/apt/sources.list
121 deb http://the.earth.li/debian/ jessie main non-free contrib
127 =head1 WHAT DGIT CLONE PRODUCES
129 =head2 What branches are there
131 dgit clone will give you a new working tree,
132 and arrange for you to be on a branch like
135 There is a tracking branch for the contents of the archive, called
136 C<remotes/dgit/dgit/jessie>
137 (and similarly for other suites). This can be updated with
138 C<dgit fetch jessie>.
139 This, the I<remote suite branch>,
140 is synthesized by your local copy of dgit.
141 It is fast forwarding.
143 (You can also dgit fetch in a tree that wasn't made by dgit clone.
144 If there's no C<debian/changelog>
145 you'll have to supply a C<-p>I<package> option to dgit fetch.)
147 =head2 What kind of source tree do you get
149 If the Debian package is based on some upstream release,
150 the code layout should be like the upstream version.
151 You should find C<git grep> helpful to find where to edit.
153 The package's Debian metadata and the scripts for building binary
154 packages are under C<debian/>.
155 C<debian/control>, C<debian/changelog> and C<debian/rules> are the
157 The Debian Policy Manual has most of the in-depth
160 For many Debian packages,
161 there will also be some things in C<debian/patches/>.
162 It is best to ignore these.
163 Insofar as they are relevant
164 the changes there will have been applied to the actual files,
165 probably by means of actual comments in the git history.
166 The contents of debian/patches are ignored
167 when building binaries
168 from dgitish git branches.
170 (For Debian afficionados:
171 the git trees that come out of dgit are
172 "patches-applied packaging branches".)
174 =head2 What kind of history you get
176 If you're lucky, the history will be a version of,
178 the Debian maintainer's own git history,
179 or upstream's git history.
181 But for many packages the real git history
183 or has not been published in a dgitish form.
184 So yuu may find that the history is a rather short
185 history invented by dgit.
187 dgit histories often contain automatically-generated commits,
188 including commits which make no changes but just serve
189 to make a rebasing branch fast-forward.
191 If the package maintainer is using git then
193 you may find that there is a useful C<vcs-git> remote
194 referring to the Debian package maintainer's repository
196 You can see what's there with C<git fetch vcs-git>.
197 But use what you find there with care:
198 Debian maintainers' git repositories often have
199 contents which are very confusing and idiosyncratic.
200 In particular, you may need to manually apply the patches
201 that are in debian/patches before you do anything else!
205 =head2 Always commit before building
209 % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
210 % git commit -a -m 'Fix libc lost output bug'
214 Debian package builds are often quite messy:
215 they may modify files which are also committed to git,
216 or leave outputs and teporary files not covered by C<.gitignore>.
218 Kf you always commit,
228 to tidy up after a build.
229 (If you forgot to commit, don't use those commands;
230 instead, you may find that you can use C<git add -p>
231 to help commit what you actually wanted to keep.)
233 These are destructive commands which delete all new files
234 (so you B<must> remember to say C<git add>)
235 and throw away edits to every file
236 (so you B<must> remember to commit).
238 =head2 Update the changelog (at least once) before building
242 % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
246 The binaries you build will have a version number which ultimately
247 comes from the C<debian/changelog>.
248 You want to be able to tell your
249 binaries apart from your distro's.
251 So you should update C<debian/changelog>
252 to add a new stanza at the top,
255 This rune provides an easy way to do this.
256 It adds a new changelog
257 entry with an uninformative message and a plausible version number
258 (containing a bit of your git commit id).
260 If you want to be more sophisticated,
261 the package C<dpkg-dev-el> has a good Emacs mode
262 for editing changelogs.
263 Alternatively, you could edit the changelog with another text editor,
264 or run C<dch> or C<gbp dch> with different options.
265 Choosing a good version number is slightly tricky and
266 a complete treatment is beyond the scope of this tutorial.
268 =head2 Actually building
272 % sudo apt-get build-dep glibc
273 % dpkg-buildpackage -uc -b
277 apt-get build-dep installs the build dependencies according to the
278 official package, not your modified one. So if you've changed the
279 build dependencies you might have to install some of them by hand.
281 dpkg-buildpackage is the primary tool for building a Debian source
283 C<-uc> means not to pgp-sign the results.
284 C<-b> means build all binary packages,
285 but not to build a source package.
291 % sudo dpkg -i ../libc6_*.deb
295 You can use C<dpkg -i> to install the
296 .debs that came out of your package.
298 If the dependencies aren't installed,
299 you will get an error, which can usually be fixed with
300 C<apt-get -f install>.
304 If you're working on a library package and your system has multiple
305 architectures enabled,
306 you may see something like this:
310 dpkg: error processing package libpcre3-dev:amd64 (--configure):
311 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)
315 The multiarch system used by Debian requires each package which is
316 present for multiple architectures to be exactly the same across
317 all the architectures for which it is installed.
320 is to build the package for all the architectures you
322 You'll need a chroot for each of the secondary architectures.
323 This iw somewhat tiresome,
324 even though Debian has excellent tools for managing chroots.
325 C<sbuild-createchroot> from the sbuild package is a
328 Otherwise you could deinstall the packages of interest
329 for those other architectures
330 with something like C<dpkg --remove libpcre3:i386>.
332 If neither of those are an option,
333 your desperate last resort is to try
334 using the same version number
335 as the official package for your own package.
336 (The verseion is controlled by C<debian/changelog> - see above,)
337 This is not ideal because it makes it hard to tell what is installed,
338 because it will mislead and confuse apt.
340 With the "same number" approach you may still get errors like
344 trying to overwrite shared '/usr/include/pcreposix.h', which is different from other instances of package libpcre3-dev
348 but passing C<--force-overwrite> to dpkg will help
349 - assuming you know what you're doing.
351 =head1 SHARING YOUR WORK
353 The C<dgit/jessie> branch (or whatever) is a normal git branch.
354 You can use C<git push> to publish it on any suitable git server.
356 Anyone who gets that git branch from you
357 will be able to build binary packages
360 If you want to contribute your changes back to Debian,
361 you should probably send them as attachments to
363 L<Debian Bug System|https://bugs.debian.org/>
364 (either a followup to an existing bug, or a new bug).
365 Patches in C<git-format-patch> format are usually very welcome.
367 =head2 Source packages
370 git branch is not sufficient to build a source package
372 Source packages are somewhat awkward to work with.
373 Indeed many plausible git histories or git trees
374 cannot be converted into a suitable source package.
375 So I recommend you share your git branch instead.
377 If a git branch is not enough, and
378 you need to provide a source package
379 but don't care about its format/layout
380 (for example because some software you have consumes source packages,
382 you can use this recipe to generate a C<1.0> "native"
383 source package, which is just a tarball
384 with accompanying .dsc metadata file:
388 % git rm debian/source/version
389 % git commit -m 'switch to 1.0 source format'
390 % dgit -wgf --dpkg-buildpackage:-sn build-source
394 If you need to provide a good-looking source package,
395 be prepared for a lot more work.
396 You will need to read much more, perhaps starting with
397 L<dgit-nmu-simple(7)>,
398 L<dgit-sponsorship(7)> or