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
|
<chapter id="gbp.patches">
<title>Working with patches</title>
<para>&gbp-pq; can be used to manage patches inside
<filename>debian/patches/</filename>. The basic idea is that patches are
imported to a local <filename>patch-queue/master</filename> branch (with one
commit on the <filename>patch-queue/master</filename> branch representing
exactly one patch in <filename>debian/patches/</filename>). There, the
maintainer will work on them using usual &git; commands (rebase, commit
--amend, etc). When done, &gbp-pq; will be used to export the patches to
<filename>debian/patches/</filename>. This workflow facilitates the
cherry-picking of patches for stable releases, and the forward-porting of
patches to new upstream versions by using git rebase on the
<filename>patch-queue/master</filename> branch (patches already applied
upstream are detected automatically). The generated patches in debian/patches/
have all the necessary information to forward them upstream given they are auto
generated via git-format-patch.</para>
<para>The main drawback of this workflow is the lack of history on the
<filename>patch-queue/master</filename> branch (but there is full history on
the <filename>master</filename> branch, of course).</para>
<sect1 id="gbp.patches.workflow">
<title>Workflow</title>
<para>Assuming the Debian source package has its patches in
<filename>debian/patches</filename> and these are parseable by
<command>git-quiltimport(1)</command>:</para>
<para>Create patch-queue branch and import debian/patches onto it using gbp-pq:</para>
<screen>
<command>cd <replaceable>REPO</replaceable></command>
<command>gbp pq import</command>
</screen>
<para>This will switch you to the <filename>patch-queue</filename> branch
automatically. If you started from <filename>master</filename> the
<filename>patch-queue</filename> branch will be called
<filename>patch-queue/master</filename>.</para>
<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 debian/patches/ 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 master. The git documentation
explains how to work with git-rebase.</para></listitem>
</itemizedlist></para>
<para>Regenerate the patches in <filename>debian/patches/</filename> using
&gbp-pq;. This will switch you back to master and regenerate the patches using
<command>git-format-patch(1)</command>:</para>
<screen>
<command>gbp pq export</command>
</screen>
<para>Commit the result either by using gbp-add-patch or simply</para>
<screen>
<command>git add debian/patches</command>
<command>git commit</command>
</screen>
<para>Update debian/changelog (e.g. by running "git-dch -S -a")</para>
<para>Build the package</para>
<para>After importing a new upstream version you can use the following commands
to refresh debian/patches:</para>
<screen>
<command>gbp pq rebase</command>
<command>git checkout master</command>
<command>gbp pq export</command>
</screen>
<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, this will switch to the proper branch
<screen>
<command>gbp pq import</command>
</screen>
<listitem><para>Create your first patch: edit files, test, commit your changes using <command>git commit</command></para></listitem>
<listitem><para>Back to the master branch, generate the Quilt patch set
<screen>
<command>git checkout master</command>
<command>gbp pq export</command>
</screen></para></listitem>
<listitem><para>Commit you first patch
<screen>
<command>git add -a debian/patches/</command>
<command>git commit -m 'my first patch'</command>
</screen></para></listitem>
</orderedlist>
<para>If you want to pick the changelog message from the patch see
<filename>/usr/share/doc/git-buildpackage/examples/gbp-add-patch</filename>.</para>
<para>
In order to avoid a patched (unclean) source tree after the build, you
can use &dpkg-source;'s <option>unapply-patches</option> option and
tell &git; to ignore the <filename>.pc</filename> directory.
<filename>/usr/share/doc/git-buildpackage/examples/gbp-configure-unpatched-source</filename>
sets up these two files for you.
</para>
</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>
<screen>
<command>git branch -d patch-queue/master</command>
<command>gbp pq import</command>
</screen>
<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 debian/patches):</para>
<screen>
<command>gbp pull --redo-pq</command>
</screen>
<para>
However you can push out patch-queue branches. Other team members must just be
aware that that branches in the patch-queue/ namespace are being rebased
frequently.
</para>
</sect1>
<sect1 id="gbp.patches.30quilt">
<title>Working with 3.0 (quilt) packges</title>
<para>
The 3.0 (quilt) format applies the patches in debian/patches automatically when
building a source package. If you want your debian branch to contain the
unpatched source there are several ways to handle this:
</para>
<itemizedlist>
<listitem><para>Using <filename>debian/source/local-options</filename>:
You can use <option>unapply-patches</option> in
<filename>debian/source/local-options</filename> to unapply the patches after
the build.
<filename>/usr/share/doc/git-buildpackage/examples/gbp-configure-unpatched-source</filename>
will this set up for you when run from inside a git repository of a Debian
package.
</para></listitem>
<listitem><para>Using <option>--git-export-dir</option>:
If you are using option <option>--git-export-dir</option> already there is no
problem since the unpatched source tree gets exported before being built (and
patch by dpkg-source). Since this implies an extra copy of the whole source
tree (which might be slow for big projects) and it is not really necessary when
using pbuilder the next method might be more appropriate.
</para></listitem>
<listitem><para>
Working from a patch-queue branch.
Instead of building from master build from patch-queue/master prepared by
gbp-pq as describe above. This branch has the patches already applied as
dpkg-source expects it:</para>
<screen>
<command>gbp pq import</command>
<command>gbp buildpackage --git-debian-branch=patch-queue/master</command>
Build and test...
<command>git checkout master</command>
<command>gbp pq export</command>
</screen>
</listitem>
</itemizedlist>
</chapter>
|
