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
|
<chapter id="gbp.intro">
<title>Introduction</title>
<para>
Welcome to &gbp;, a system that integrates the
<ulink url="http://www.debian.org/">Debian</ulink> package build
system with <ulink url="http://git.or.cz/">Git</ulink>. The current version of this manual can be found
<ulink url="https://honk.sigxcpu.org/piki/projects/git-buildpackage">here</ulink>.
</para>
<para>
What can these tools do for you:
<itemizedlist>
<listitem><para>Import an existing &debian; package into &git;</para></listitem>
<listitem><para>Import new upstream versions, NMUs etc. with optional filters</para></listitem>
<listitem><para>Automatic upstream tarball generation</para></listitem>
<listitem><para>Maintain a consistent branch and tag naming across
repositories or across a team of developers</para></listitem>
<listitem><para>Automatically sign tags</para></listitem>
<listitem><para>Automatically push changes to remote repositories</para></listitem>
<listitem><para>Make sure you have committed all changes to the right
branch before releasing</para></listitem>
<listitem><para>Export to a clean build area before building</para></listitem>
<listitem><para>Automatic debian/changelog generation</para></listitem>
<listitem><para>Automatic generation of snapshot releases for local testing</para></listitem>
<listitem><para>Simple patch management</para></listitem>
</itemizedlist>
All of this is (hopefully) being done without restricting the user to certain usage patterns.
</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>) 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>) holds the upstream releases. This can
either be a branch you import to or a branch of an upstream repository
you pull from.</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
branches</option>. 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 recommended branch layout is described in <xref linkend="gbp.branch.naming"/>.
</para>
<para>Since &gbp-buildpackage; only works with local &git;-repositories,
you have to use <command>git push</command> in order to publish your
changes to remote repositories like <ulink
url="http://git.debian.org/">git.debian.org</ulink>; this can also be
automatized with &gbp-buildpackage;'s <option>post-tag</option>
hook.</para>
</sect1>
<sect1 id="gbp.workflow">
<title>Workflow</title>
<para>
A typical, simple workflow consists of the following steps:
</para>
<orderedlist>
<listitem><para>Import a new &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>
|
