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
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
|
<chapter id="gbp.patches">
<title>Working with patches</title>
<para>
&gbp-pq; can be used to manage patches that modify the upstream
source inside
<filename>debian/patches/</filename>. This is mostly intended for
3.0 (quilt) format source packages.
</para>
<para>
The basic idea is that patches are imported from you
&debian-branch; to a patch-queue branch with one patch file
in <filename>debian/patches/</filename> becoming one commit on the
the patch-queue branch. The created branch will be named after
the branch you imported from
with <filename>patch-queue/</filename> prepended. So if you do
your &debian; packaging on <filename>debian/sid</filename> and do
a
</para>
<programlisting>
&gbp-pq-import;
</programlisting>
<para>
then the newly created branch will be
called <filename>patch-queue/debian/sid</filename>.
</para>
<para>On the patch-queue branch you can work on the commits using
familiar &git; commands (rebase, commit --amend, etc). When done,
&gbp-pq; will be used to turn the commits on the patch-queue
branch into patch in <filename>debian/patches/</filename> files
again.
</para>
<para>
This workflow facilitates e.g. the cherry-picking of patches for
stable releases, the forward-porting of patches to new upstream
versions by using git rebase on the patch-queue branch (patches
already applied upstream are detected automatically) as well as
the reordering, dropping and renaming of patches without having to
resort to &quilt;. The generated patches
in <filename>debian/patches/</filename> have all the necessary
information to forward them upstream since they use a format similar
to <command>git-format-patch</command>.
</para>
<para>
The main drawback of this workflow is the lack of history on the
patch-queue branch since it is frequently droppend and
recreated. But there is full history on
the your &debian-branch;, of course.
</para>
<sect1 id="gbp.patches.workflow">
<title>Basic Workflow</title>
<para>
This example assumes you're working on a source 3.0 (quilt)
format package with patches
in <filename>debian/patches</filename> parseable
by <command>git-quiltimport(1)</command>. The git branch
currently checked out is named <filename>debian/sid</filename>.
</para>
<mediaobject>
<imageobject>
<imagedata fileref="images/pq-unapplied.png" format="PNG"/>
</imageobject>
<caption>
<para>
The &debian-branch; we start from.
</para>
</caption>
</mediaobject>
<para>Let's first create the patch-queue branch and import the
contents of <filename>debian/patches</filename> onto it using
&gbp-pq;
</para>
<programlisting>
<command>cd <replaceable>REPO</replaceable></command>
&gbp-pq; import
</programlisting>
<para>
This will generate output like:
<screen>
gbp:info: Trying to apply patches at 'aaa1011bfd5aa74fea43620aae94709de05f80be'
gbp:info: 18 patches listed in 'debian/patches/series' imported on 'patch-queue/debian/sid'
</screen>
What happened is that &gbp-pq; imported each patch file and switched
you to the newly created patch-queue branch
(<filename>patch-queue/debian/sid</filename>) automatically.
</para>
<mediaobject>
<imageobject>
<imagedata fileref="images/pq-applied.png" format="PNG"/>
</imageobject>
<caption>
<para>
The patch-queue branch with patches
from <filename>debian/patches</filename> applied.
</para>
</caption>
</mediaobject>
<para>
Now you can work on the patch-queue branch (add, remove, rebase,
test) to get your patches into shape:
<itemizedlist>
<listitem>
<para>
To add what will later become a patch
in <filename>debian/patches/</filename> simply make a
commit. The first line of the commit message will become the
patch name later. The following lines include the details of
what the patch does.
</para>
</listitem>
<listitem>
<para>
To remove or edit commits use git rebase -i . The git
documentation explains how to work with git-rebase.
</para>
</listitem>
</itemizedlist>
</para>
<para>
Once satisfied with the commits let's regenerate the patches
in <filename>debian/patches/</filename> using &gbp-pq;. This will
switch you back to the branch <filename>debian/sid</filename> and
regenerate the patches using a method similar
to <command>git-format-patch</command>:
</para>
<programlisting>
&gbp-pq; export
</programlisting>
<para>You can now commit the result by using:</para>
<programlisting>
&gitcmd; add debian/patches
&gitcmd; commit
</programlisting>
<para>
If you don't want to commit the result by hand each time you can also
pass <option>--commit</option> to the &gbp; <option>export</option>
command above.
</para>
<para>
Next you can update <filename>debian/changelog</filename> (e.g. by
running "&gbp-dch; <option>-S</option> <option>-a</option>") and
build the package as usual.
</para>
</sect1>
<sect1 id="gbp.patches.newupstream">
<title>Importing a new upstream version</title>
<para>
To update your patches for a new upstream version one
</para>
<orderedlist>
<listitem>
<para>
Imports the current patches onto the patch-queue branch (if
not done already) using &gbp-pq-import;. This will allow you
to rebase the patches on the new upstream version later.
</para>
</listitem>
<listitem>
<para>
Imports the new upstream version with
&gbp-import-orig; <option>--uscan</option>.
</para>
</listitem>
<listitem>
<para>
Rebases the patches onto the new upstream version using
&gbp-pq-rebase;. This will bring the patches up to date
regarding the new upstream version. Patches already applied
upstream can be dropped and remaining patches can be modified
to apply to the new version.
</para>
</listitem>
<listitem>
<para>
Exports the patches to <filename>debian/patches</filename> using
&gbp-pq-export;.
</para>
</listitem>
</orderedlist>
<para>
But don't worry if you forgot to do so before importing the new
version (or if another team member imported the version already).
</para>
<para>
In this case you can make &gbp-pq; figure out where to apply the
patches by using the <option>--time-machine=</option> option. The
following command
</para>
<programlisting>
&gbp-pq-import; --force --time-machine=10
</programlisting>
<para>
would drop your current patch-queue branch (if existent) and
create a new one by going back in your commit history as far as 10
commits to find a place where your patches still
apply <footnote><para>This is not necessarily
your debian-branch; HEAD since the new upstream
version might have changed so that the patches no longer apply
cleanly there.</para></footnote>. If it finds such a commit on
your &debian-branch; it will create the patch-queue branch from
there and switch you to that branch. You can now rework your
patches to apply to the new upstream version by using
&gbp-pq-rebase;:
</para>
<mediaobject>
<imageobject>
<imagedata fileref="images/pq-time-machine.png" format="PNG"/>
</imageobject>
<caption>
<para>
The patch-queue branch and &debian-branch; after importing the
patches.
</para>
</caption>
</mediaobject>
<programlisting>
&gbp-pq-rebase;
</programlisting>
<para>
or you can invoke &gitcmd; <option>rebase</option> directly:
</para>
<programlisting>
&gitcmd; rebase -i debian/sid
</programlisting>
<para>
Should the rebase fail (e.g. because the upstream source changed
at the same place your patches modify the code) you can resolve
this by using the options of &gitcmd; <option>rebase</option> (if
you simply want to abort use
&gitcmd; <option>rebase</option> <option>--abort</option>).
</para>
<mediaobject>
<imageobject>
<imagedata fileref="images/pq-rebase.png" format="PNG"/>
</imageobject>
<caption>
<para>
The patch-queue branch after rebasing the patches. Patches
that were merged upstream were dropped.
</para>
</caption>
</mediaobject>
<para>
Once done you can export your commits to patch files again:
</para>
<programlisting>
&gbp-pq-export; --commit
</programlisting>
<para>
The export will also switch you back to the &debian-branch;.
</para>
<mediaobject>
<imageobject>
<imagedata fileref="images/pq-export.png" format="PNG"/>
</imageobject>
<caption>
<para>
The &debian-branch; after exporting the patches and committing the changes.
</para>
</caption>
</mediaobject>
<para>
See this in action in a
<ulink url="https://honk.sigxcpu.org/piki/projects/git-buildpackage/videos/gbp-pq-new-upstream-version.ogv">short
video</ulink>.
</para>
</sect1>
<sect1 id="gbp.patches.firstpatch">
<title>Adding your first patch</title>
<para>
If a package doesn't have any patches yet, these are the steps to add
your first patch:
</para>
<orderedlist>
<listitem>
<para>Launch an import. If there's nothing to import &gbp-pq; will just
create an empty branch and switch your working copy to it:
<programlisting>
&gbp-pq-import;
</programlisting>
</para>
</listitem>
<listitem>
<para>
Create your first patch: edit files, test, commit your changes
using <command>git commit</command>
</para>
</listitem>
<listitem>
<para>
To generate the new Quilt patch set use
</para>
<programlisting>
&gbp-pq-export; --commit
</programlisting>
<para>
This will switch you back to your &debian-branch; branch, generate the
patches and commit them right away to this branch.
</para>
<para>
Skip the <option>--commit</option> if you don't want to commit
right away. If you want to pick the changelog message from the patch
see
<filename>/usr/share/doc/git-buildpackage/examples/gbp-add-patch</filename>.
</para>
</listitem>
</orderedlist>
</sect1>
<sect1 id="gbp.patches.team">
<title>Team maintenance</title>
<para>The easiest way is to not push out any patch-queue/* branches at all.
They can be recreated by any team member easily by using</para>
<programlisting>
&gbp-pq-import; --force
</programlisting>
<para>
The patch-queue branch can also be re-created when pulling (this
will additionally drop your current patch-queue branch and recreate it
from <filename>debian/patches</filename>):</para>
<programlisting>
&gbp-pull; --redo-pq
</programlisting>
<para>
Note that you can you can push out patch-queue branches. Other team
members must just be aware that branches in the patch-queue/
namespace are being rebased frequently and therefore cause
non fast-forward updates.
</para>
</sect1>
</chapter>
|