1dgit-user(7)                         dgit                         dgit-user(7)
2
3
4

NAME

6       dgit-user - making and sharing changes to Debian packages, with git
7

INTRODUCTION

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
12       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
15       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
19       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

SUMMARY

24       (These runes will be discussed later.)
25
26           % 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
35       Occasionally:
36
37           % git clean -xdf
38           % git reset --hard
39
40       Later:
41
42           % 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

FINDING THE RIGHT SOURCE CODE - DGIT CLONE

49           % dgit clone glibc jessie,-security
50           % cd glibc
51
52       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
57   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
61           % 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
69       (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
73   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
82       If you don't know what you're running, try this:
83
84           % grep '^deb' /etc/apt/sources.list
85           deb http://the.earth.li/debian/ jessie main non-free contrib
86           ...
87           %
88
89       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

WHAT DGIT CLONE PRODUCES

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
99       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
105       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
111       (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
115   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
120       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
125       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
132       (For Debian afficionados: the git trees that come out of dgit are
133       "patches-applied packaging branches without a .pc directory".)
134
135   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
139       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
143       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
148       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

BUILDING

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
162       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
166       If you always commit, you can use
167
168           % git clean -xdf
169           % git reset --hard
170
171       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
175       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
179   Update the changelog (at least once) before building
180           % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
181
182       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
186       So you should update "debian/changelog" to add a new stanza at the top,
187       for your build.
188
189       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
193       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
199   Actually building
200           % mk-build-deps --root-cmd=sudo --install
201           % dpkg-buildpackage -uc -b
202
203       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
207   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
211           % git clean -xdf
212           % sbuild -c jessie -A --no-clean-source \
213                    --dpkg-source-opts='-Zgzip -z1 --format=1.0 -sn'
214
215       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

INSTALLING

221   Debian Jessie or older
222           % sudo dpkg -i ../libc6_*.deb
223
224       You can use "dpkg -i" to install the .debs that came out of your
225       package.
226
227       If the dependencies aren't installed, you will get an error, which can
228       usually be fixed with "apt-get -f install".
229
230   Debian Stretch or newer
231           % sudo apt install ../libc6_*.deb
232

Multiarch

234       If you're working on a library package and your system has multiple
235       architectures enabled, you may see something like this:
236
237           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
240       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
244       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
251       Otherwise you could deinstall the packages of interest for those other
252       architectures with something like "dpkg --remove libpcre3:i386".
253
254       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
260       With the "same number" approach you may still get errors like
261
262           trying to overwrite shared '/usr/include/pcreposix.h', which is
263           different from other instances of package libpcre3-dev
264
265       but passing "--force-overwrite" to dpkg will help - assuming you know
266       what you're doing.
267

SHARING YOUR WORK

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
273       Anyone who gets that git branch from you will be able to build binary
274       packages (.deb) just as you did.
275
276       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
282   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
289       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
295           % 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
299       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

SEE ALSO

304       dgit(1), dgit(7)
305
306
307
308perl v5.38.0                    Debian Project                    dgit-user(7)
Impressum