summaryrefslogtreecommitdiff
path: root/dgit-user.7.pod
blob: 54bfa1d0c815d7960d277ad0d87cb705c3229660 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
=head1 NAME

dgit - tutorial for users of Debian-derived distros supported by dgit

=head1 INTRODUCTION

dgit lets you fetch the source code to every package on your
system
 as if your distro used git to maintain all of it.

You can then edit it,
build updated binary packages
and install and run them.
You can also share your work with others.

This tutorial assumes you have basic familiarity with git.
It does not assume any initial familiarity with
 Debian's packaging processes.

=head1 SUMMARY

=over 4

    % dgit clone glibc jessie
    % cd glibc
    % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
    % git commit -a -m 'Fix libc lost output bug'
    % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
    % sudo apt-get build-dep glibc
    % dpkg-buildpackage -uc -b
    % sudo dpkg -i ../libc6_*.deb

=back

Later:

=over 4

    % cd glibc
    % dgit pull jessie
    % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
    % dpkg-buildpackage -uc -b
    % sudo dpkg -i ../libc6_*.deb

=back

=head1 FINDING THE RIGHT SOURCE CODE - DGIT CLONE

dgit clone needs to be told the source package name
(which might be different to the binary package name)
and the codename of the Debian release
(this is called the "suite").

=head2 Finding the source package name

For many packages, the source package name is obvious.
Otherwise, if you know a file that's in the package,
you can look it up with dpkg:

=over 4

    % dpkg -S /lib/i386-linux-gnu/libc.so.6 
    libc6:i386: /lib/i386-linux-gnu/libc.so.6
    % dpkg -s libc6:i386
    Package: libc6
    Status: install ok installed
    ...
    Source: glibc

=back

(In this example,
libc6 is a "multi-arch: allowed" package,
 which means that it exists in several different builds
 for different architectures.
That's where C<:i386> comes from.)

=head2 Finding the Debian release (the "suite")

Internally,
Debian (and derived) distros normally refer to their releases by codenames.
So for example, at the time of writing
Debian C<jessie> (Debian 8) is Debian stable and
the current version of Ubuntu is C<yakkety> (Yakkety Yak, 16.10).

If you don't know what you're running, try this:

=over 4

    % grep '^deb' /etc/apt/sources.list
    deb http://the.earth.li/debian/ jessie main non-free contrib
    ...
    %

=back

=head1 EDITING THE SOURCE CODE

=head2 What kind of source tree you get when you dgit clone

If the Debian package is actually a version of an upstream release,
the code layout should be like the upstream version.
You should find that git commands C<git grep> work properly.

The package's Debian metadata and the script for building binary
packages are under C<debian/>.
C<debian/control>, C<debian/changelog> and C<debian/rules> are the
starting points.
The Debian Policy Manual has most of the in-depth
technical details.

For many Debian packages,
there will also be some things in C<debian/patches/>.
These will probably be in your git history
(one way or another),
and they are not used when building a package
based on a git histroy obtained with dgit.
It is best to ignore them.

=head2 What kind of history you get

If you're lucky, the history will be a version of,
or based on,
the Debian maintainer's own git history,
or upstream's git history.

But for many packages the real git history
does not exist or
cannot be obtained in a standard form
So yuu may find that the history is a rather short
history invented by dgit.

dgit histories often contain automatically-generated commits,
including commits which make no changes but just serve
to make a rebasing branch fast-forward.

If the package maintainer is using git then
after dgit clone
you may find that there is a useful C<vcs-git> remote
referring to the Debian package maintainers repository
for the pacakge.
You can see what's there with C<git fetch vcs-git>.
But use what you find there with care:
Debian maintainers' git histories are often in
formats which are very confusing and idiosyncratic
from the point of view of those new to Debian git packaging.

=head1 BUILDING

=head2 Always commit first

When using git with some arbitrary Debian package
you should normally commit before building.

This is because Debian package builds are often quite messy:
they may modify files which are also committed to git,
or leave outputs and teporary files not covered by C<.gitignore>.
Kf you always commit,
you can use C<git reset --hard> and C<git clean -xdf>
to put things back.
But if you create a new file
B<don't forget> to say C<git add>, and commit,
as otherwise C<git clean> will delete your new file.

=head2 Update the changelog (at least once)

The binaries you build will have a version number which ultimately
comes from the C<debian/changelog>.  You want to be able to tell your
binaries apart from your distro's.

So you should update C<debian/changelog>
to add a new stanza at the top,
for your build.
An easy way to do this is this rune:

=over 4

    % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit

=back

which adds a new entry with a new version number chosen in a
reasonably sensible way, and commits the result to your git branch.

=head1 INSTALLING

You can use C<dpkg -i> to install the
.debs that came out of your package.

If the dependencies aren't installed,
you will get an error, which can usually be fixed with
C<apt-get -f install>.

=head1 SHARING YOUR WORK

The C<dgit/jessie> branch (or whatever) is a normal git branch.
You can use C<git push> to any suitable git server.

If you want to contribute your changes back to Debian,
you should probably send them as attachments to 
an email to the
L<Debian Bug System|https://bugs.debian.org/>
(either a followup to an existing bug, or a new bug).
Patches in C<<git-format-patch> format are usually very welcome.

Anyone who gets that git branch from you
will be able to build binary packages
just as you did.

However, the
git branch is not sufficient to build a I<source package>.
Source packages are somewhat awkward to work with.
Indeed many plausible git histories or git trees
cannot be converted into a suitable source package.
So I recommend you share your git branch instead.
If you need to provide a source package,
you will probably want to read one of the other tutorials,
such as L<dgit-nmu-simple(7)>, L<dgit-sponsorship(7)> or
 L<dgit-maint-*(7)>

multi-arch clash problem


xxx

=head1 SEE ALSO

dgit(1), dgit(7)

=head1 AUTHOR

This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>.  It contains contributions from other dgit contributors too - see the dgit copyright file.