path: root/docs/chapters/import.sgml

<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>
&gitcmd; branch upstream
<command>dh_make</command>
    </screen>
    That's it, you're done.
    </sect1>
</chapter>