aboutsummaryrefslogtreecommitdiff
path: root/docs/chapters/special.sgml
blob: 8f4305727253662e926f413fd97766c0fc425b3a (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
    <chapter id="gbp.special">
    <title>Special usage cases</title>
    <sect1 id="gbp.special.dfsgfree">
    <title>Handling non-DFSG clean upstream sources</title>
    <para>If you have to handle non DFSG clean upstream sources you can use a
    different branch which you have to create once:
    <screen>
&gitcmd; branch dfsg_clean upstream
    </screen>
    <para>
    This creates the <emphasis>dfsg_clean</emphasis> branch from the tip of a
    branch called <emphasis>upstream</emphasis>.  Then, when importing a new
    upstream version, you import the new version on the
    <option>upstream-branch</option> (by default named
    <emphasis>upstream</emphasis>) as usual and just don't merge to the
    <emphasis>debian-branch</emphasis>  (by default named
    <emphasis>master</emphasis>):
    </para>
    <screen>
&git-import-orig; --no-merge <filename>/path/to/nondfsg-clean-package_10.4.orig.tar.gz</filename>
&gitcmd; <option>tag</option> 10.4
    </screen>
    <para>
    After the import you can switch to the <emphasis>dfsg_clean</emphasis>
    branch and get the newly imported changes from the upstream branch:
    </para>
    <screen>
&gitcmd; <option>checkout</option> dfsg_clean
&gitcmd; <option>pull</option> <filename>.</filename> upstream
    </screen>
    <para>Now make this checkout dfsg clean (preverably by a cleanup script), commit
    your changes and merge to your <option>debian-branch</option>:</para>
    <screen>
cleanup-script.sh
&gitcmd; commit -a -m "Make source dfsg clean"
&gitcmd; tag <replaceable>10.4.dfsg</replaceable>
&gitcmd; checkout <replaceable>master</replaceable>
&gitcmd; pull <replaceable>.</replaceable> <replaceable>dfsg_clean</replaceable>
    </screen>

    <sect1 id="gbp.special.nmus">
    <title>Importing NMUs</title>
    <para>
    First create a branch that holds the NMUs from the tip of your
    <option>debian-branch</option> (default is <emphasis>master</emphasis>) once:
    </para>
    <screen>
&gitcmd; <option>branch</option> <replaceable>nmu</replaceable> <replaceable>master</replaceable>
    </screen>
    <para>
    To import an NMU change into the git repository and use &git-import-dsc;:
    </para>
    <screen>
&gitcmd; checkout <replaceable>master</replaceable>
&git-import-dsc; <option>--debian-branch</option>=<replaceable>nmu</replaceable> <filename>/path/to/package_1.0-1nmu0.dsc</filename>
    </screen>
    <para>
    This will import the NMU onto the branched named <emphasis>nmu</emphasis>
    instead of the default <option>master</option>. This method can also
    be used to import "old" releases into the &git; repository when migrating
    to &git; from another VCS.
    </para>
    </sect1>

    <sect1 id="gbp.special.pbuilder">
    <title>Using &pbuilder;</title>
    <para>
    Since &pbuilder; uses different command line arguments than
    &debuild; and &dpkg-buildpackage; we can't simply pass the options on the
    command line but have to wrap them in the <option>--git-builder</option>
    option instead:

<programlisting>
<command>git-buildpackage</command> <option>--git-builder="pdebuild --debbuildopts '-I.git -i\.git"</option>  <option>--git-cleaner="fakeroot debian/rules clean"</option>
</programlisting>

    Note that we also used a different clean command since since &pdebuildcmd;
    <option>clean</option> means something different than &debuildcmd;
    <option>clean</option>.
    
    The above is a bit long, so using a tiny script that gets invoked by
    &git-buildpackage; is more convienient:

<programlisting>
cat &lt;&lt;EOF &gt;/usr/local/bin/git-pbuilder
#!/bin/sh
# pass commandline arguments to dpkg-buildpackage
<command>pdebuild</command> <option>--debbuildopts</option> "-i\.git -I.git $*"
EOF
<command>chmod</command> a+x /usr/local/bin/git-pbuilder
</programlisting>

	This makes the above look like:

<programlisting>
<command>git-buildpackage</command> <option>--git-builder=git-pbuilder</option>  <option>--git-cleaner="fakeroot debian/rules clean"</option>
</programlisting>

	We can shorten this further by using <filename>~/.gbp.conf</filename>:

<programlisting>
cat &lt;&lt;EOF &gt; <filename>~/.gbp.conf</filename>
[DEFAULT]
# tell git-buildpackage howto clean the source tree
cleaner = fakeroot debian/rules clean
# this is how we invoke pbuilder, arguments passed to git-buildpackage will be
# passed to dpkg-buildpackge in the chroot
builder = /usr/local/bin/git-pbuilder
</programlisting>

	Invoking &git-buildpackage; will now invoke &pdebuildcmd; by
	default and all additional command line arguments are passed to
	dpkg-buildpackage. If you want to use debuild again (without modifying
	<filename>~/.gbp.conf</filename>) you can use:
<programlisting>
<command>git-buildpackage</command> --git-builder=debuild
</programlisting>

	Futhrermore, if you don't want this for all your invocations of
	&git-buildpackage; you can use <filename>.git/gbp.conf</filename> in
	one of your &git; repositories instead of
	<filename>~/.gbp.conf</filename>.
    </para>

    <sect1 id="gbp.special.hacking">
    <title>Working on random packages</title>
    <para>
    Whenever you need to work on an arbitrary Debian package you can check it
    right into &git; with one command:
<programlisting>
apt-get source --download-only <filename>package</filename>
git-import-dsc <filename>package</filename>*.dsc
cd <filename>package</filename>
git-branch debian
</programlisting>
    <para>
    This puts the orig.tar.gz onto the <option>upstream-branch</option> and
    the Debian patch onto a branch called <emphasis>debian</emphasis>. Now you
    can easily modify the package, revert changes you made, create other
    branches for testing, see what changes you made, etc..  When finished just
    do</para>
<programlisting>
git-commit -a
git-diff debian --
</programlisting>
    <para>
    to get a nice patch that can be submitted to the Debian BTS.
    </para>
    </sect1>
</chapter>