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
|
<chapter id="gbp.intro">
<title>Introduction</title>
<para>
Welcome to git-buildpackage (short &gbp;), a system that integrates the
<ulink url="https://www.debian.org/">Debian</ulink> package build
system with <ulink url="https://git-scm.com/doc">Git</ulink>. The most
recent version of this manual can be found at &manual;.
</para>
<para>
This is what &gbp; can do for you:
</para>
<itemizedlist>
<listitem><para>Import existing &debian; packages into &git;</para></listitem>
<listitem><para>Incrementally import new versions of a Debian
package into &git; e.g. for importing NMUs or to maintain
downstream modifications</para></listitem>
<listitem><para>Import new upstream versions from tarballs or git tags, or both at the same time</para></listitem>
<listitem><para>Automatically apply debian/copyright filters for DFSG-clean imports</para></listitem>
<listitem><para>Recreate (bit-for-bit with pristine-tar) the upstream tarball from information stored in &git;</para></listitem>
<listitem><para>Maintain a consistent branch and tag naming within a &git; repository, across
repositories or across a team of developers</para></listitem>
<listitem><para>Automatically sign generated tags</para></listitem>
<listitem><para>Make sure you have committed all changes to the right
branch before building and releasing</para>
</listitem>
<listitem><para>Execute hooks at various points of the package
build process e.g. to automatically push changes to remote
repositories</para>
</listitem>
<listitem><para>Integrate the build process with cowbuilder or other builders</para></listitem>
<listitem><para>Export to a clean build area before building the package</para></listitem>
<listitem><para>Generate <filename>debian/changelog</filename> automatically</para></listitem>
<listitem><para>Add, edit and rebase the <filename>debian/patche</filename> without having to use GNU Quilt</para></listitem>
<listitem>
<para>
Pull changes from remote repositories like
<ulink url="https://salsa.debian.org/">salsa.debian.org</ulink>
</para>
</listitem>
<listitem>
<para>
Publish changes to remote packaging repositories like
<ulink url="https://salsa.debian.org/">salsa.debian.org</ulink>
</para>
</listitem>
</itemizedlist>
<para>
All of this is (hopefully) being done without restricting the user to certain usage patterns.
</para>
<para>
Git-buildpackage utlizises among others
<ulink url="https://manpages.debian.org/unstable/devscripts/uscan.1.en.html">uscan</ulink>,
<ulink url="https://manpages.debian.org/unstable/pristine-tar/pristine-tar.1.en.html">pristine-tar</ulink>,
<ulink url="https://manpages.debian.org/unstable/devscripts/debchange.1.en.html">debchange</ulink>
and <ulink url="https://manpages.debian.org/unstable/devscripts/debuild.1.en.html">debuild</ulink>
(which in turn uses
<ulink url="https://manpages.debian.org/unstable/dpkg-dev/dpkg-buildpackage.1.en.html">dpkg-buildpackage</ulink>
and <ulink url="https://manpages.debian.org/unstable/lintian/lintian.1.en.html">lintian</ulink>).
Prior knowledge about these tools transfer easily to git-buildpackage as
for example the configuration options have the same names. However, people
learning Debian packaging do not need to know these tools as
git-buildpackage will by default use these tools correctly on behalf of
the user. Leveraging on these tools also means that git-buildpackage has
all the capabilities these tools have, and git-buildpackage is equally
compliant to all Debian policies as these tools are.
</para>
<sect1 id="gbp.repository">
<title>Repository Layout and Terminology</title>
<para>It is recommended to have the &debian; packaging on a separate
branch than the upstream source <footnote><para>this, of course, has
no meaning for &debian; native packages</para></footnote>.
This is necessary to be able to import
and merge in new upstream versions via &gbp-import-orig;.
To distinguish these two branches, the following terminology
<footnote><para>corresponding to the command
line and config file options</para></footnote> is used:
</para>
<itemizedlist>
<listitem><para>The <option>debian-branch</option> (the default branch name
used in the &git; repository is <emphasis>master</emphasis> and in DEP-14
<emphasis>debian/latest</emphasis>) holds your current development work.
That's the branch you usually cut your releases from and the default branch
new upstream releases are merged onto.</para></listitem>
<listitem><para> The <option>upstream-branch</option> (the default branch name
used in the &git; repository is <emphasis>upstream</emphasis> and in DEP-14
<emphasis>upstream/latest</emphasis>) holds the upstream releases. Note that
this branch is to contain the upstream source code as it was at the time of
the upstream release, which was imported into Debian packaging. It is not
intended to point to the tip of the upstream development branch. The branch
contents is updated by extracting the upstream source tarball into it, or by
pulling from an upstream release tag.</para></listitem>
<listitem><para> The <option>pristine-tar branch</option> (the default
branch name used in the &git; repository is
<emphasis>pristine-tar</emphasis>) holds the necessary additional
information to recreate the original tarball from the
<option>upstream-branch</option>. In order to use this feature, you need
to install the &pristine-tar; package.</para></listitem>
<listitem><para> There can be one or more <option>patch-queue</option> branches.
Every patch-queue branch is related to a
<option>debian-branch</option>. If the <option>debian-branch</option> is called
<emphasis>master</emphasis>, the corresponding patch-queue branch is
called <emphasis>patch-queue/master</emphasis>. The patch-queue branch is
the &debian; branch plus the contents of
<emphasis>debian/patches</emphasis> applied. These branches are managed
with &gbp-pq;.
</para></listitem>
</itemizedlist>
<para>You're completely
free to pick any repository layout; the branch names above are only
&gbp;'s defaults. They can be changed at any point in time,
and you can work with an arbitrary number of branches.
For example, branches like <emphasis>nmu</emphasis>,
<emphasis>backports</emphasis> or <emphasis>stable</emphasis> might
(temporarily or permanently) become your <option>debian-branch</option>,
and branches like <emphasis>dfsg</emphasis> or
<emphasis>snapshots</emphasis> might become your
<option>upstream-branch</option>—it doesn't matter if these branches
are maintained with &gbp-import-orig; or not.</para>
<para>
A flexible, recommended branch layout compatible with DEP-14 is
described in the section <xref linkend="gbp.branch.naming"/>.
</para>
<para>Since &gbp-buildpackage; only works with local &git;-repositories,
you have to use <command>git push</command> or <command>gbp
push</command>in order to publish your changes to remote repositories
like <ulink
url="https://salsa.debian.org/">salsa.debian.org</ulink>; this can be
automated with &gbp-buildpackage;'s <option>post-tag</option>
hook.</para>
<mediaobject>
<imageobject>
<imagedata fileref="images/dep-14-branch-examples.svg" format="SVG"/>
</imageobject>
<caption><para>Example of git history when DEP-14 is used.</para></caption>
</mediaobject>
</sect1>
<sect1 id="gbp.workflow">
<title>Workflow</title>
<para>
A typical, simple workflow consists of the following steps:
</para>
<orderedlist>
<listitem><para>Initially import a &debian; package via &gbp-import-dsc;. This
imports the &debian; Package on the <option>debian-branch</option>
and the upstream sources on the <option>upstream-branch</option>.</para></listitem>
<listitem><para>Develop, test, commit changes. During this time, you can
always build the package with &gbp-buildpackage;. In case you have
uncommitted changes in your source tree, you can use the
<option>--git-ignore-new</option> option.</para></listitem>
<listitem><para>Optionally you can create the &debian; changelog entries
using &gbp-dch; and create snapshot releases for testing using its
<option>--snapshot</option> option.</para></listitem>
<listitem><para>Once satisfied, you can build the final package with
&gbp-buildpackage; <option>--git-tag</option>. This additionally
creates a tag within &git; so you can switch back to that version later
at any time. The format of the tags can be specified; tags can
be &gpg; signed.</para></listitem>
<listitem><para>When a new upstream version is released and upstream
isn't using &git;, you can import the new version via &gbp-import-orig;
onto the <option>upstream-branch</option>. &gbp-import-orig; will
by default try to merge the new upstream version onto the
<option>debian-branch</option> (you can skip the merge with
<option>--no-merge</option>). After resolving any potential conflicts,
go back to the second step.</para></listitem>
</orderedlist>
<para>These steps will be explained in more details in the following sections.</para>
</sect1>
</chapter>
|
