docs/chapters/import.sgml


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

<chapter id="gbp.import">
    <title>Importing Sources</title>
    <sect1 id="gbp.import.existing">
    <title>Importing already existing &debian; packages</title>
    <para>Imporing 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 put the upstream sources onto the <emphasis>upstream</emphasis>
    branch and the debian patch on the <emphasis>master</emphasis> branch. In case
    of a debian native package only the <emphasis>master</emphasis> branch is being
    used.
    You can specify different branch names via the
    <option>--upstream-branch</option> and <option>--debian-branch</option> options.
    </para>
    </sect1>
    <sect1 id="gbp.import.new.upstream">
    <title>Importing a new upstream version</title>
    <para>Change into your git repository, make sure it has all local
    modifications committed and run either of:
    <screen>
&git-import-orig; /path/to/package_0.2.orig.tar.gz
&git-import-orig; /path/to/package_0.2.tar.bz2
&git-import-orig; /path/to/package-0.2/
    </screen>
    This puts the upstream souces onto the <emphasis>upstream</emphasis> branch.
    The result of this is then merged onto the <emphasis>master</emphasis>
    branch and a new 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; --filter='CVS/*' /path/to/package_0.2.orig.tar.gz
    </screen>
    </para> 
    <para>
    If you expect a merge conflict you can delay the merge to
    <emphasis>master</emphasis> via the <option>--no-merge</option> and pull in
    the changes from the <emphasis>upstream</emphasis> branch any time later.
    </para>
    <para>
    </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 <emphasis>upstream</emphasis>
    with:
    <screen>
mv .git/theupstream-branch .git/upstream
    </screen> 
    or you can tell &git-buildpackage; the name of the branch:
    <screen>
cat &lt;&lt;EOF &gt; <filename>.git/gbp.conf</filename>
[DEFAULT]
# this is the upstream-branch:
upstream-branch=theupstream-branch
    </screen>
    If you use &git-import-orig; to import new upstream sources, they will
    end up on <emphasis>theupstream-branch</emphasis> and merged to
    <emphasis>master</emphasis>.
    </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
    <emphasis>upstream</emphasis> branch 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; should
    work as expected.</para>
    </sect2>
    </sect1>
</chapter>