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
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 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 =head1 WHAT DGIT CLONE PRODUCES
130 =head2 What branches are there
132 dgit clone will give you a new working tree,
133 and arrange for you to be on a branch like
136 There is a tracking branch for the contents of the archive, called
137 C<remotes/dgit/dgit/jessie>
138 (and similarly for other suites). This can be updated with
139 C<dgit fetch jessie>.
140 This, the I<remote suite branch>,
141 is synthesized by your local copy of dgit.
142 It is fast forwarding.
144 (You can also dgit fetch in a tree that wasn't made by dgit clone.
145 If there's no C<debian/changelog>
146 you'll have to supply a C<-p>I<package> option to dgit fetch.)
148 =head2 What kind of source tree do you get
150 If the Debian package is based on some upstream release,
151 the code layout should be like the upstream version.
152 You should find C<git grep> helpful to find where to edit.
154 The package's Debian metadata and the scripts for building binary
155 packages are under C<debian/>.
156 C<debian/control>, C<debian/changelog> and C<debian/rules> are the
158 The Debian Policy Manual has most of the in-depth
161 For many Debian packages,
162 there will also be some things in C<debian/patches/>.
163 It is best to ignore these.
164 Insofar as they are relevant
165 the changes there will have been applied to the actual files,
166 probably by means of actual comments in the git history.
167 The contents of debian/patches are ignored
168 when building binaries
169 from dgitish git branches.
171 (For Debian afficionados:
172 the git trees that come out of dgit are
173 "patches-applied packaging branches
174 without a .pc directory".)
176 =head2 What kind of history you get
178 If you're lucky, the history will be a version of,
180 the Debian maintainer's own git history,
181 or upstream's git history.
183 But for many packages the real git history
185 or has not been published in a dgitish form.
186 So yuu may find that the history is a rather short
187 history invented by dgit.
189 dgit histories often contain automatically-generated commits,
190 including commits which make no changes but just serve
191 to make a rebasing branch fast-forward.
193 If the package maintainer is using git then
195 you may find that there is a useful C<vcs-git> remote
196 referring to the Debian package maintainer's repository
198 You can see what's there with C<git fetch vcs-git>.
199 But use what you find there with care:
200 Debian maintainers' git repositories often have
201 contents which are very confusing and idiosyncratic.
202 In particular, you may need to manually apply the patches
203 that are in debian/patches before you do anything else!
207 =head2 Always commit before building
211 % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
212 % git commit -a -m 'Fix libc lost output bug'
216 Debian package builds are often quite messy:
217 they may modify files which are also committed to git,
218 or leave outputs and teporary files not covered by C<.gitignore>.
220 Kf you always commit,
230 to tidy up after a build.
231 (If you forgot to commit, don't use those commands;
232 instead, you may find that you can use C<git add -p>
233 to help commit what you actually wanted to keep.)
235 These are destructive commands which delete all new files
236 (so you B<must> remember to say C<git add>)
237 and throw away edits to every file
238 (so you B<must> remember to commit).
240 =head2 Update the changelog (at least once) before building
244 % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
248 The binaries you build will have a version number which ultimately
249 comes from the C<debian/changelog>.
250 You want to be able to tell your
251 binaries apart from your distro's.
253 So you should update C<debian/changelog>
254 to add a new stanza at the top,
257 This rune provides an easy way to do this.
258 It adds a new changelog
259 entry with an uninformative message and a plausible version number
260 (containing a bit of your git commit id).
262 If you want to be more sophisticated,
263 the package C<dpkg-dev-el> has a good Emacs mode
264 for editing changelogs.
265 Alternatively, you could edit the changelog with another text editor,
266 or run C<dch> or C<gbp dch> with different options.
267 Choosing a good version number is slightly tricky and
268 a complete treatment is beyond the scope of this tutorial.
270 =head2 Actually building
274 % sudo apt-get build-dep glibc
275 % dpkg-buildpackage -uc -b
279 apt-get build-dep installs the build dependencies according to the
280 official package, not your modified one. So if you've changed the
281 build dependencies you might have to install some of them by hand.
283 dpkg-buildpackage is the primary tool for building a Debian source
285 C<-uc> means not to pgp-sign the results.
286 C<-b> means build all binary packages,
287 but not to build a source package.
291 =head2 Debian Jessie or older
295 % sudo dpkg -i ../libc6_*.deb
299 You can use C<dpkg -i> to install the
300 .debs that came out of your package.
302 If the dependencies aren't installed,
303 you will get an error, which can usually be fixed with
304 C<apt-get -f install>.
306 =head2 Debian Stretch or newer
310 % sudo apt install ../libc6_*.deb
316 If you're working on a library package and your system has multiple
317 architectures enabled,
318 you may see something like this:
322 dpkg: error processing package libpcre3-dev:amd64 (--configure):
323 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)
327 The multiarch system used by Debian requires each package which is
328 present for multiple architectures to be exactly the same across
329 all the architectures for which it is installed.
332 is to build the package for all the architectures you
334 You'll need a chroot for each of the secondary architectures.
335 This iw somewhat tiresome,
336 even though Debian has excellent tools for managing chroots.
337 C<sbuild-createchroot> from the sbuild package is a
340 Otherwise you could deinstall the packages of interest
341 for those other architectures
342 with something like C<dpkg --remove libpcre3:i386>.
344 If neither of those are an option,
345 your desperate last resort is to try
346 using the same version number
347 as the official package for your own package.
348 (The verseion is controlled by C<debian/changelog> - see above,)
349 This is not ideal because it makes it hard to tell what is installed,
350 because it will mislead and confuse apt.
352 With the "same number" approach you may still get errors like
356 trying to overwrite shared '/usr/include/pcreposix.h', which is different from other instances of package libpcre3-dev
360 but passing C<--force-overwrite> to dpkg will help
361 - assuming you know what you're doing.
363 =head1 SHARING YOUR WORK
365 The C<dgit/jessie> branch (or whatever) is a normal git branch.
366 You can use C<git push> to publish it on any suitable git server.
368 Anyone who gets that git branch from you
369 will be able to build binary packages (.deb)
372 If you want to contribute your changes back to Debian,
373 you should probably send them as attachments to
375 L<Debian Bug System|https://bugs.debian.org/>
376 (either a followup to an existing bug, or a new bug).
377 Patches in C<git-format-patch> format are usually very welcome.
379 =head2 Source packages
382 git branch is not sufficient to build a source package
384 Source packages are somewhat awkward to work with.
385 Indeed many plausible git histories or git trees
386 cannot be converted into a suitable source package.
387 So I recommend you share your git branch instead.
389 If a git branch is not enough, and
390 you need to provide a source package
391 but don't care about its format/layout
392 (for example because some software you have consumes source packages,
394 you can use this recipe to generate a C<1.0> "native"
395 source package, which is just a tarball
396 with accompanying .dsc metadata file:
400 % git rm debian/source/version
401 % git commit -m 'switch to 1.0 source format'
402 % dgit -wgf --dpkg-buildpackage:-sn build-source
406 If you need to provide a good-looking source package,
407 be prepared for a lot more work.
408 You will need to read much more, perhaps starting with
409 L<dgit-nmu-simple(7)>,
410 L<dgit-sponsorship(7)> or