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".)
175 =head2 What kind of history you get
177 If you're lucky, the history will be a version of,
179 the Debian maintainer's own git history,
180 or upstream's git history.
182 But for many packages the real git history
184 or has not been published in a dgitish form.
185 So yuu may find that the history is a rather short
186 history invented by dgit.
188 dgit histories often contain automatically-generated commits,
189 including commits which make no changes but just serve
190 to make a rebasing branch fast-forward.
192 If the package maintainer is using git then
194 you may find that there is a useful C<vcs-git> remote
195 referring to the Debian package maintainer's repository
197 You can see what's there with C<git fetch vcs-git>.
198 But use what you find there with care:
199 Debian maintainers' git repositories often have
200 contents which are very confusing and idiosyncratic.
201 In particular, you may need to manually apply the patches
202 that are in debian/patches before you do anything else!
206 =head2 Always commit before building
210 % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
211 % git commit -a -m 'Fix libc lost output bug'
215 Debian package builds are often quite messy:
216 they may modify files which are also committed to git,
217 or leave outputs and teporary files not covered by C<.gitignore>.
219 Kf you always commit,
229 to tidy up after a build.
230 (If you forgot to commit, don't use those commands;
231 instead, you may find that you can use C<git add -p>
232 to help commit what you actually wanted to keep.)
234 These are destructive commands which delete all new files
235 (so you B<must> remember to say C<git add>)
236 and throw away edits to every file
237 (so you B<must> remember to commit).
239 =head2 Update the changelog (at least once) before building
243 % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
247 The binaries you build will have a version number which ultimately
248 comes from the C<debian/changelog>.
249 You want to be able to tell your
250 binaries apart from your distro's.
252 So you should update C<debian/changelog>
253 to add a new stanza at the top,
256 This rune provides an easy way to do this.
257 It adds a new changelog
258 entry with an uninformative message and a plausible version number
259 (containing a bit of your git commit id).
261 If you want to be more sophisticated,
262 the package C<dpkg-dev-el> has a good Emacs mode
263 for editing changelogs.
264 Alternatively, you could edit the changelog with another text editor,
265 or run C<dch> or C<gbp dch> with different options.
266 Choosing a good version number is slightly tricky and
267 a complete treatment is beyond the scope of this tutorial.
269 =head2 Actually building
273 % sudo apt-get build-dep glibc
274 % dpkg-buildpackage -uc -b
278 apt-get build-dep installs the build dependencies according to the
279 official package, not your modified one. So if you've changed the
280 build dependencies you might have to install some of them by hand.
282 dpkg-buildpackage is the primary tool for building a Debian source
284 C<-uc> means not to pgp-sign the results.
285 C<-b> means build all binary packages,
286 but not to build a source package.
292 % sudo dpkg -i ../libc6_*.deb
296 You can use C<dpkg -i> to install the
297 .debs that came out of your package.
299 If the dependencies aren't installed,
300 you will get an error, which can usually be fixed with
301 C<apt-get -f install>.
305 If you're working on a library package and your system has multiple
306 architectures enabled,
307 you may see something like this:
311 dpkg: error processing package libpcre3-dev:amd64 (--configure):
312 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)
316 The multiarch system used by Debian requires each package which is
317 present for multiple architectures to be exactly the same across
318 all the architectures for which it is installed.
321 is to build the package for all the architectures you
323 You'll need a chroot for each of the secondary architectures.
324 This iw somewhat tiresome,
325 even though Debian has excellent tools for managing chroots.
326 C<sbuild-createchroot> from the sbuild package is a
329 Otherwise you could deinstall the packages of interest
330 for those other architectures
331 with something like C<dpkg --remove libpcre3:i386>.
333 If neither of those are an option,
334 your desperate last resort is to try
335 using the same version number
336 as the official package for your own package.
337 (The verseion is controlled by C<debian/changelog> - see above,)
338 This is not ideal because it makes it hard to tell what is installed,
339 because it will mislead and confuse apt.
341 With the "same number" approach you may still get errors like
345 trying to overwrite shared '/usr/include/pcreposix.h', which is different from other instances of package libpcre3-dev
349 but passing C<--force-overwrite> to dpkg will help
350 - assuming you know what you're doing.
352 =head1 SHARING YOUR WORK
354 The C<dgit/jessie> branch (or whatever) is a normal git branch.
355 You can use C<git push> to publish it on any suitable git server.
357 Anyone who gets that git branch from you
358 will be able to build binary packages (.deb)
361 If you want to contribute your changes back to Debian,
362 you should probably send them as attachments to
364 L<Debian Bug System|https://bugs.debian.org/>
365 (either a followup to an existing bug, or a new bug).
366 Patches in C<git-format-patch> format are usually very welcome.
368 =head2 Source packages
371 git branch is not sufficient to build a source package
373 Source packages are somewhat awkward to work with.
374 Indeed many plausible git histories or git trees
375 cannot be converted into a suitable source package.
376 So I recommend you share your git branch instead.
378 If a git branch is not enough, and
379 you need to provide a source package
380 but don't care about its format/layout
381 (for example because some software you have consumes source packages,
383 you can use this recipe to generate a C<1.0> "native"
384 source package, which is just a tarball
385 with accompanying .dsc metadata file:
389 % git rm debian/source/version
390 % git commit -m 'switch to 1.0 source format'
391 % dgit -wgf --dpkg-buildpackage:-sn build-source
395 If you need to provide a good-looking source package,
396 be prepared for a lot more work.
397 You will need to read much more, perhaps starting with
398 L<dgit-nmu-simple(7)>,
399 L<dgit-sponsorship(7)> or