# Importing Sources

# Importing already existing Debian packages

Importing an already exsting debian package into a git repository is as easy as:

    gbp import-dsc package_0.1-1.dsc

This will create a new git repository named after the imported package, put the upstream sources onto the `upstream-branch` and the debian patch on the `debian-branch`. In case of a debian native package only the `debian-branch` is being used. You can specify alternative branch names via the `--upstream-branch` and `--debian-branch` options or via the `upstream-branch` and `debian-branch` options in the configuration file.

If you want to be able to exactly recreate the original tarball (orig.tar.gz) from Git you should also specify the `--pristine-tar` option. This is recommended.

If you want to import further versions you can change into your shiny new Git repository and just continue with the same command:

    cd package/
    gbp import-dsc package_0.1-2.dsc
    gbp import-dsc package_0.1-3.dsc
    gbp import-dsc package_0.2-1.dsc

Or you can import all versions at once using gbp import-dscs:

    gbp import-dscs /path/to/history/package_*.dsc

This will create a Git repository if necessary and import all versions sorted by version number.

# Importing a new upstream version

Change into your git repository (which can be empty), make sure it has all local modifications committed and run either of:

    gbp import-orig /path/to/package_0.2.orig.tar.gz
    gbp import-orig /path/to/package_0.2.tar.bz2
    gbp import-orig /path/to/package-0.2/

This puts the upstream souces onto the `upstream-branch` and tags them accordingly (the default tag format is `upstream/%(version)s`). The result is then merged onto the `debian-branch` and a new Debian changelog entry is created. You can again specify different branch names via the `--upstream-branch` and `--debian-branch` options. You can also filter out content you don't want imported:

    gbp import-orig --filter='CVS/*' /path/to/package_0.2.orig.tar.gz

The `--filter` option can be used multiple times for more complex filtering.

If you expect a merge conflict you can delay the merge to the `debian-branch` via the `--no-merge` and pull in the changes from the `upstream-branch` later.

If you want to be able to exactly recreate the original tarball (orig.tar.gz) from Git you should also specify the `--pristine-tar` option. This is recommended.

To customize the commit message used by gbp import-orig use the `--import-msg` option. This string is a standard python format string, into which the `version` variable is interpolated. (i.e., use `%(version)s` in your message to get the imported upstream version).

# Converting an existing Git repository

If the Git repository wasn't created with gbp import-dsc you have to tell gbp buildpackage and friends where to find the upstream sources.

## Upstream sources on a branch

If the upstream sources are already on a separate branch things are pretty simple. You can either rename that branch to the default `upstream-branch` name upstream with:

    git branch upstream theupstream-branch
    git branch -D theupstream-branch

or you can tell gbp buildpackage the name of the branch to use as `upstream-branch`:

    cat <<EOF > .git/gbp.conf
    [DEFAULT]
    # this is the upstream-branch:
    upstream-branch=theupstream-branch
    EOF

If you then use gbp import-orig to import new upstream sources, they will from now on end up on theupstream-branch and merged to the `debian-branch`.

## Upstream sources not on a branch

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 gitk or git-log to locate the commit-id of that commit and create the upstream branch from there, e.g.:

        COMMIT_ID=`git log --pretty=oneline | tail -1 | awk '{ print $1 }'`
        git branch upstream $COMMIT_ID

The important thing here is that the `COMMIT_ID` specifies a point on the master branch that carried only the upstream sources and not the debian modifications. The above example assumes that this was the first commit to that repository.

Warning
There's currently no easy way to create the `upstream-branch` if you never had the upstream sources as a single commit. Using gbp import-orig on such repositories might lead to unexpected merge results.

In order to fix this you can prepend the upstream sources as a single commit to your tree using Git's grafts. Afterwards you can simply create a branch as explained above and gbp import-orig will work as expected.

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:

        git checkout --orphan upstream
        git rm -rf .
        git commit --allow-empty -m 'Initial upstream branch.'
        git checkout -f master

With Git versions lower than 1.7.2.3, the commands are slightly more complicated:

        git symbolic-ref HEAD refs/heads/upstream
        git rm --cached -r .
        git commit --allow-empty -m 'Initial upstream branch.'
        git checkout -f master

# Starting a Debian package from scratch

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:

    mkdir package-0.1
    cd package-0.1
    git init

Then you import the upstream sources, branch off the `upstream-branch` branch and add the debian files (e.g. via dh_make):

    gbp import-orig -u 0.1 ../package-0.1.tar.gz
    dh_make

That's it, you're done. If you want to publish you're new repository you can use gbp create-remote-repo.

# When upstream uses GIT

If upstream already uses git for packaging there are several ways to handle packaging. Two of them will be described in a bit detail here:

## No upstream tarballs

If upstream doesn't build upstream tarballs or you don't care about them the simplest way is to clone upstreams repository and create a separate packaging branch in there.

In order to help gbp buildpackage to find upstream tags you need to specify the format using the `--git-upstream-tag` comand line option or the the `upstream-tag` configuration variable.

A common upstream format is to put a `v` in front of the version number. In this case the configuration option would look like:

    [git-buildpackage]
    upstream-tag = v%(version)s

`version` will be replaced with the upstream version number as read from `debian/changelog`.

If you're using pristine-tar you can make gbp buildpackage commit the generated tarball back to the pristine-tar branch by using the `--git-pristine-tar-commit` option. This will make sure others building your package can regenerate the tarball you generated for building the Debian pacakge.

### Step by step

To not make any assumptions about gbp's configuration the following steps have all options given in its long versions on the command line . You can add these to `gbp.conf` to save lots of typing.

First we clone the upstream repository. To avoid any dis ambiguities between the Debian packaging repository and the upstream repository we name the upstream repository `ustream` instead of the default `origin`.

    	    git clone --no-checkout -o upstream git://git.example.com/libgbp.git
    	    cd libgbp
    	    git checkout -b debian/sid v1.0

The above makes sure we have `debian/sid` for the Debian packaging. We didn't create any `upstream/*` branches, they're not needed for the packaging and only need to be kept up to date. After adding the Debian packaging we build the package. This assumes you're using pristine-tar and upstream uses a version number format as described above:

    	    gbp buildpackage --git-pristine-tar --git-pristine-tar-commit --git-upstream-tag='v%(version)s' --git-debian-branch=debian/sid

When updating to a new upstream version we simply fetch from upstream and merge in the new tag. Afterwards we update the changelog and build the package:

    	    git fetch upstream
    	    git merge v1.1
    	    gbp dch --debian-branch=debian/sid --snapshot --auto debian/
    	    gbp buildpackage --git-ignore-new --git-pristine-tar --git-pristine-tar-commit --git-upstream-tag='v%(version)s'

Note that the above gbp dch call makes sure we only pickup changes in the `debian/` directory. Since we told it to build a snapshot changelog entry and we didn't commit the changelog yet we need to tell gbp buildpackage that the working directory is unclean via the `--git-ignore-new`. Once everything looks good commit the changelog and build a release version:

    	    gbp dch --release --auto --git-debian-branch=debian/sid
    	    git commit -m"Release 1.1-1" debian/changelog
    	    gbp buildpackage --git-upstream-tag='v%(version)s' --git-debian-branch=debian/sid

If you want to share you're repository with others you can use gbp create-remote-repo and gbp pull as usual.

## Upstream tarballs

If you want to track upstream's git but continue to import the upstream tarballs, e.g. to make sure the tarball uploaded to Debian has the same checksum as upstream's you can use the `--upstream-vcs-tag` option when importing new tarballs with gbp import-orig. Assuming you have the upstream source in your repository with a tag `v0.0.1` you can use:

    	    gbp import-orig --upstream-vcs-tag=v0.0.1 foo_0.0.1.orig.tar.gz

to add upstream's tag as additional parent to the merge commit. See #664771 for more details.

# Branch layout

By default gbp uses one branch to keep the Debian packaging called master and a branch to keep the upstream packaging called upstream.

This layout is simple to get started but fails short if one needs to maintain several versions of the package at the same time. Therefore the following layout is recommended:

debian/<release> | the Debian packaging for a release jessie, wheezy, sid or experimental.
upstream/<release> | the upstream sources for a release matching one of the above
security/<release> | security updates for a certain release
backports/<release> | backports to a certain release
dfsg/<release> | the dfsg clean upstream sources in case the cleanup is done via a Git merge from upstream to this branch.

In case pristine-tar is being used there will be a single pristine-tar branch that keeps all binary deltas.