aboutsummaryrefslogtreecommitdiff
path: root/docs/chapters/import.sgml
blob: 3da7bd3549cc44ddecf83da6e199090870a46889 (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
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
<chapter id="gbp.import">
    <title>Importing Sources</title>

    <sect1 id="gbp.import.existing">
    <title>Importing already existing &debian; packages</title>
    <para>Importing an already exsting debian package into a git repository is as easy as:
    <screen>
&git-import-dsc; package_0.1-1.dsc
    </screen>
    This will create a new git repository named after the imported package, put
    the upstream sources onto the <option>upstream-branch</option> and the
    debian patch on the <option>debian-branch</option>. In case of a debian
    native package only the <option>debian-branch</option> is being used.
    You can specify alternative branch names via the
    <option>--upstream-branch</option> and <option>--debian-branch</option>
    options or via the <option>upstream-branch</option> and
    <option>debian-branch</option> options in the configuration file.
    </para>
    <para>
    If you want to be able to exactly recreate the original tarball
    (orig.tar.gz) from &git; you should also specify the
    <option>--pristine-tar</option> option.  This is recommended.
    </para>
    <para>
    If you want to import further versions you can change into your shiny new
    &git; repository and just continue with the same command:
    <screen>
cd package/
&git-import-dsc; package_0.1-2.dsc
&git-import-dsc; package_0.1-3.dsc
&git-import-dsc; package_0.2-1.dsc
    </screen>
    </para>
    <para>
Or you can import all versions at once using &git-import-dscs;:
    <screen>
&git-import-dscs; /path/to/history/package_*.dsc
    </screen>
This will create a &git; repository if necessary and import all versions sorted
by version number.
    </para>
    </sect1>

    <sect1 id="gbp.import.new.upstream">
    <title>Importing a new upstream version</title>
    <para>Change into your git repository (which can be empty), make sure it
    has all local modifications committed and run either of:
    <screen>
&git-import-orig; <filename>/path/to/package_0.2.orig.tar.gz</filename>
&git-import-orig; <filename>/path/to/package_0.2.tar.bz2</filename>
&git-import-orig; <filename>/path/to/package-0.2/</filename>
    </screen>
    This puts the upstream souces onto the <option>upstream-branch</option> and
    tags them accordingly (the default tag format is
    <replaceable>upstream/&lt;version&gt;</replaceable>).
    The result is then merged onto the <option>debian-branch</option>
    and a new &debian; changelog entry is created. You can again specify
    different branch names via the <option>--upstream-branch</option> and
    <option>--debian-branch</option> options. You can also filter out content
    you don't want imported:
    <screen>
&git-import-orig; <option>--filter</option>=<replaceable>'CVS/*'</replaceable> <filename>/path/to/package_0.2.orig.tar.gz</filename>
    </screen>
    The <option>--filter</option> option can be used multiple times for more
    complex filtering.
    </para> 
    <para>
    If you expect a merge conflict you can delay the merge to the
    <option>debian-branch</option> via the <option>--no-merge</option> and pull in
    the changes from the <option>upstream-branch</option> later.
    </para>
    <para>
    If you want to be able to exactly recreate the original tarball
    (orig.tar.gz) from &git; you should also specify the
    <option>--pristine-tar</option> option.  This is recommended.
    </para>
    </sect1>

    <sect1 id="gbp.import.convert">
    <title>Converting an existing &git; repository</title>
    <para>
    If the &git; repository wasn't created with &git-import-dsc; you have to tell
    &git-buildpackage; and friends where to find the upstream sources.
    <sect2>
    <title>Upstream sources on a branch</title>
    <para>
    If the upstream sources are already on a separate branch things are pretty
    simple. You can either rename that branch to the default
    <option>upstream-branch</option> name <emphasis>upstream</emphasis> with:
    <screen>
&gitcmd; branch upstream theupstream-branch
&gitcmd; branch <option>-D</option> theupstream-branch
    </screen> 
    or you can tell &git-buildpackage; the name of the branch to use as
    <option>upstream-branch</option>:
    <screen>
<command>cat</command> &lt;&lt;EOF &gt; <filename>.git/gbp.conf</filename>
[DEFAULT]
# this is the upstream-branch:
upstream-branch=theupstream-branch
EOF
    </screen>
    If you then use &git-import-orig; to import new upstream sources, they will
    from now on end up on <emphasis>theupstream-branch</emphasis> and
    merged to the <option>debian-branch</option>.
    </para>
    </sect2>
    <sect2>
    <title>Upstream sources not on a branch</title>
    <para>
    If you don't have an upstream branch but started your repository with only
    the upstream sources (not the debian patch) you can simply branch from that
    point. So use &gitkcmd; or &gitcmd;-log to locate the commit-id of that commit
    and create the upstream branch from there, e.g.:
<screen>
    COMMIT_ID=`&gitcmd; log --pretty=oneline | tail -1 | awk '{ print $1 }'`
    &gitcmd; branch upstream $COMMIT_ID
</screen>
    The important thing here is that the <envar>COMMIT_ID</envar> specifies a
    point on the master branch that carried <emphasis>only</emphasis> the
    upstream sources and not the debian modifications. The above example
    assumes that this was the first commit to that repository.
    </para>
    <warning><para>There's currently no <emphasis>easy</emphasis> way to create the
    <option>upstream-branch</option> if you never had the upstream sources
    as a single commit. Using &git-import-orig; on such repositories might lead
    to unexpected merge results.</para></warning>
    <para>In order to fix this you can prepend the upstream sources as a
    single commit to your tree using &git;'s <ulink
    url="http://git.or.cz/gitwiki/GraftPoint">grafts</ulink>. Afterwards you
    can simply create a branch as explained above and &git-import-orig; will 
    work as expected.</para>
    <para>Alternatively, if you are only importing source from original tarballs
    (for instance when converting from a Subversion repository where the
    mergeWithUpstream was set for svn-buildpackage), you can create an empty
    upstream branch with the following commands:
<screen>
    git symbolic-ref HEAD refs/heads/upstream
    git rm --cached -r .
    git commit --allow-empty -m 'Initial upstream branch.'
    git checkout -f master
</screen>
    </para>
    </sect2>
    </sect1>

    <sect1 id="gbp.import.fromscratch">
    <title>Starting a Debian package from scratch</title>
    <para>
    So far we assumed you already have a &debian; package to start with but
    what if you want to start a new package? First create an empty repository:
    </para>
    <screen>
<command>mkdir</command> package-0.1
<command>cd</command> package-0.1
<command>git init</command>
    </screen> 
    <para>Then you import the upstream sources, branch off the
    <option>upstream-branch</option> branch and add the debian files (e.g. via dh_make):
    <screen>
&git-import-orig; <option>-u</option> <replaceable>0.1</replaceable> <filename>../package-0.1.tar.gz</filename>
<command>dh_make</command>
    </screen>
    That's it, you're done.
    </sect1>
</chapter>