1dgit-user(7) dgit dgit-user(7)
2
6 dgit-user - making and sharing changes to Debian packages, with git
7
9 dgit lets you fetch the source code to every package on your system as
10 if your distro used git to maintain all of it.
11 You can then edit it, build updated binary packages (.debs) and install
13 and run them. You can also share your work with others.
14 This tutorial gives some recipes and hints for this. It assumes you
16 have basic familiarity with git. It does not assume any initial
17 familiarity with Debian's packaging processes.
18 If you are a package maintainer within Debian; a DM or DD; and/or a
20 sponsee: this tutorial is not for you. Try dgit-nmu-simple(7),
21 dgit-maint-*(7), or dgit(1) and dgit(7).
22
24 (These runes will be discussed later.)
25 % dgit clone glibc jessie,-security
27 % cd glibc
28 % curl 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
29 % git commit -a -m 'Fix libc lost output bug'
30 % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
31 % mk-build-deps --root-cmd=sudo --install
32 % dpkg-buildpackage -uc -b
33 % sudo dpkg -i ../libc6_*.deb
34 Occasionally:
36 % git clean -xdf
38 % git reset --hard
39 Later:
41 % cd glibc
43 % dgit pull jessie,-security
44 % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
45 % dpkg-buildpackage -uc -b
46 % sudo dpkg -i ../libc6_*.deb
47
49 % dgit clone glibc jessie,-security
50 % cd glibc
51 dgit clone needs to be told the source package name (which might be
53 different to the binary package name, which was the name you passed to
54 "apt-get install") and the codename or alias of the Debian release
55 (this is called the "suite").
56 Finding the source package name
58 For many packages, the source package name is obvious. Otherwise, if
59 you know a file that's in the package, you can look it up with dpkg:
60 % dpkg -S /lib/i386-linux-gnu/libc.so.6
62 libc6:i386: /lib/i386-linux-gnu/libc.so.6
63 % dpkg -s libc6:i386
64 Package: libc6
65 Status: install ok installed
66 ...
67 Source: glibc
68 (In this example, libc6 is a "multi-arch: allowed" package, which means
70 that it exists in several different builds for different architectures.
71 That's where ":i386" comes from.)
72 Finding the Debian release (the "suite")
74 Internally, Debian (and derived) distros normally refer to their
75 releases by codenames. Debian also has aliases which refer to the
76 current stable release etc. So for example, at the time of writing
77 Debian "jessie" (Debian 8) is Debian "stable"; and the current version
78 of Ubuntu is "yakkety" (Yakkety Yak, 16.10). You can specify either
79 the codename "jessie" or the alias "stable". If you don't say, you get
80 "sid", which is Debian "unstable" - the main work-in progress branch.
81 If you don't know what you're running, try this:
83 % grep '^deb' /etc/apt/sources.list
85 deb http://the.earth.li/debian/ jessie main non-free contrib
86 ...
87 %
88 For Debian, you should add ",-security" to the end of the suite name,
90 unless you're on unstable or testing. Hence, in our example "jessie"
91 becomes "jessie,-security". (Yes, with a comma.)
92
94 What branches are there
95 dgit clone will give you a new working tree, and arrange for you to be
96 on a branch named like "dgit/jessie,-security" (yes, with a comma in
97 the branch name).
98 For each release (like "jessie") there is a tracking branch for the
100 contents of the archive, called "remotes/dgit/dgit/jessie" (and
101 similarly for other suites). This can be updated with "dgit fetch
102 jessie". This, the remote suite branch, is synthesized by your local
103 copy of dgit. It is fast forwarding.
104 Debian separates out the security updates, into "*-security". Telling
106 dgit "jessie,-security" means that it should include any updates
107 available in "jessie-security". The comma notation is a request to
108 dgit to track jessie, or jessie-security if there is an update for the
109 package there.
110 (You can also dgit fetch in a tree that wasn't made by dgit clone. If
112 there's no "debian/changelog" you'll have to supply a "-p"package
113 option to dgit fetch.)
114 What kind of source tree do you get
116 If the Debian package is based on some upstream release, the code
117 layout should be like the upstream version. You should find "git grep"
118 helpful to find where to edit.
119 The package's Debian metadata and the scripts for building binary
121 packages are under "debian/". "debian/control", "debian/changelog" and
122 "debian/rules" are the starting points. The Debian Policy Manual has
123 most of the in-depth technical details.
124 For many Debian packages, there will also be some things in
126 "debian/patches/". It is best to ignore these. Insofar as they are
127 relevant the changes there will have been applied to the actual files,
128 probably by means of actual comments in the git history. The contents
129 of debian/patches are ignored when building binaries from dgitish git
130 branches.
131 (For Debian afficionados: the git trees that come out of dgit are
133 "patches-applied packaging branches without a .pc directory".)
134 What kind of history you get
136 If you're lucky, the history will be a version of, or based on, the
137 Debian maintainer's own git history, or upstream's git history.
138 But for many packages the real git history does not exist, or has not
140 been published in a dgitish form. So you may find that the history is
141 a rather short history invented by dgit.
142 dgit histories often contain automatically-generated commits, including
144 commits which make no changes but just serve to make a rebasing branch
145 fast-forward. This is particularly true of combining branches like
146 "jessie,-security".
147 If the package maintainer is using git then after dgit clone you may
149 find that there is a useful "vcs-git" remote referring to the Debian
150 package maintainer's repository for the package. You can see what's
151 there with "git fetch vcs-git". But use what you find there with care:
152 Debian maintainers' git repositories often have contents which are very
153 confusing and idiosyncratic. In particular, you may need to manually
154 apply the patches that are in debian/patches before you do anything
155 else!
156
158 Always commit before building
159 % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
160 % git commit -a -m 'Fix libc lost output bug'
161 Debian package builds are often quite messy: they may modify files
163 which are also committed to git, or leave outputs and temporary files
164 not covered by ".gitignore".
165 If you always commit, you can use
167 % git clean -xdf
169 % git reset --hard
170 to tidy up after a build. (If you forgot to commit, don't use those
172 commands; instead, you may find that you can use "git add -p" to help
173 commit what you actually wanted to keep.)
174 These are destructive commands which delete all new files (so you must
176 remember to say "git add") and throw away edits to every file (so you
177 must remember to commit).
178 Update the changelog (at least once) before building
180 % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
181 The binaries you build will have a version number which ultimately
183 comes from the "debian/changelog". You want to be able to tell your
184 binaries apart from your distro's.
185 So you should update "debian/changelog" to add a new stanza at the top,
187 for your build.
188 This rune provides an easy way to do this. It adds a new changelog
190 entry with an uninformative message and a plausible version number
191 (containing a bit of your git commit id).
192 If you want to be more sophisticated, the package "dpkg-dev-el" has a
194 good Emacs mode for editing changelogs. Alternatively, you could edit
195 the changelog with another text editor, or run "dch" or "gbp dch" with
196 different options. Choosing a good version number is slightly tricky
197 and a complete treatment is beyond the scope of this tutorial.
198 Actually building
200 % mk-build-deps --root-cmd=sudo --install
201 % dpkg-buildpackage -uc -b
202 dpkg-buildpackage is the primary tool for building a Debian source
204 package. "-uc" means not to pgp-sign the results. "-b" means build
205 all binary packages, but not to build a source package.
206 Using sbuild
208 You can build in an schroot chroot, with sbuild, instead of in your
209 main environment. (sbuild is used by the Debian build daemons.)
210 % git clean -xdf
212 % sbuild -c jessie -A --no-clean-source \
213 --dpkg-source-opts='-Zgzip -z1 --format=1.0 -sn'
214 Note that this will seem to leave a "source package" (.dsc and .tar.gz)
216 in the parent directory, but that source package should not be used.
217 It is likely to be broken. For more information see Debian bug
218 #868527.
219
221 Debian Jessie or older
222 % sudo dpkg -i ../libc6_*.deb
223 You can use "dpkg -i" to install the .debs that came out of your
225 package.
226 If the dependencies aren't installed, you will get an error, which can
228 usually be fixed with "apt-get -f install".
229 Debian Stretch or newer
231 % sudo apt install ../libc6_*.deb
232
234 If you're working on a library package and your system has multiple
235 architectures enabled, you may see something like this:
236 dpkg: error processing package libpcre3-dev:amd64 (--configure):
238 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)
239 The multiarch system used by Debian requires each package which is
241 present for multiple architectures to be exactly the same across all
242 the architectures for which it is installed.
243 The proper solution is to build the package for all the architectures
245 you have enabled. You'll need a chroot for each of the secondary
246 architectures. This is somewhat tiresome, even though Debian has
247 excellent tools for managing chroots. "sbuild-debian-developer-setup"
248 from the package of the same name and "sbuild-createchroot" from the
249 "sbuild" package are good starting points.
250 Otherwise you could deinstall the packages of interest for those other
252 architectures with something like "dpkg --remove libpcre3:i386".
253 If neither of those are an option, your desperate last resort is to try
255 using the same version number as the official package for your own
256 package. (The version is controlled by "debian/changelog" - see
257 above.) This is not ideal because it makes it hard to tell what is
258 installed, and because it will mislead and confuse apt.
259 With the "same number" approach you may still get errors like
261 trying to overwrite shared '/usr/include/pcreposix.h', which is
263 different from other instances of package libpcre3-dev
264 but passing "--force-overwrite" to dpkg will help - assuming you know
266 what you're doing.
267
269 The "dgit/jessie,-security" branch (or whatever) is a normal git
270 branch. You can use "git push" to publish it on any suitable git
271 server.
272 Anyone who gets that git branch from you will be able to build binary
274 packages (.deb) just as you did.
275 If you want to contribute your changes back to Debian, you should
277 probably send them as attachments to an email to the Debian Bug System
278 <https://bugs.debian.org/> (either a followup to an existing bug, or a
279 new bug). Patches in "git-format-patch" format are usually very
280 welcome.
281 Source packages
283 The git branch is not sufficient to build a source package the way
284 Debian does. Source packages are somewhat awkward to work with.
285 Indeed many plausible git histories or git trees cannot be converted
286 into a suitable source package. So I recommend you share your git
287 branch instead.
288 If a git branch is not enough, and you need to provide a source package
290 but don't care about its format/layout (for example because some
291 software you have consumes source packages, not git histories) you can
292 use this recipe to generate a "3.0 (native)" source package, which is
293 just a tarball with accompanying .dsc metadata file:
294 % echo '3.0 (native)' >debian/source/format
296 % git commit -m 'switch to native source format' debian/source/format
297 % dgit -wgf build-source
298 If you need to provide a good-looking source package, be prepared for a
300 lot more work. You will need to read much more, perhaps starting with
301 dgit-nmu-simple(7), dgit-sponsorship(7) or dgit-maint-*(7)
302
304 dgit(1), dgit(7)
305perl v5.38.0 Debian Project dgit-user(7)