## 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 sources onto the `upstream-branch` and tags them accordingly (the default tag format is `upstream/%(version)s`).

The result is then placed onto the `debian-branch`. The way this happens is determined by the `--merge-mode` option. The default mode `auto` replaces the upstream sources while preserving the `debian/` directory for 3.0 (quilt) packages. A Git merge is used for all other source format versions.

You can again specify different branch names via the `--upstream-branch` and `--debian-branch` options.

If you are using `debian/watch` to keep track of how to retrieve upstream sources, you can simply use the `--uscan` option to download and import the latest upstream version:

      gbp import-orig --uscan

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` option 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 Python format string, into which the `version` variable is interpolated. (i.e., use `%(version)s` in your message to get the imported upstream version).

### Recovering from errors

In case of an error gbp import-orig will by default rollback (undo) all changes it has done to the repository so far:

    	$ gbp import-orig --verbose --filter='CVS/*' --filter='.bzr/*' --filter='.hg/*' --filter='.svn/*' --upstream-version=1.9 ../gif2apng-1.9.tar.gz
    	gbp:info: Importing '../gif2apng-1.9.tar.gz' to branch 'upstream' (filtering out ["'CVS/*'", "'.bzr/*'", "'.hg/*'", "'.svn/*'"])...
    	gbp:info: Source package is gif2apng
    	gbp:info: Upstream version is 1.9
    	gbp:info: Merging to 'master'
    	gbp:error: Automatic merge failed.
    	gbp:error: Error detected, Will roll back changes.
    	gbp:info: Rolling back branch upstream by resetting it to a6733c1f1e190ac0ed4774abc3466e9986a6df5e
    	gbp:info: Rolling back branch pristine-tar by resetting it to 0ee24ac614c920e30af82d602882c2ee841c88e5
    	gbp:info: Rolling back tag upstream/1.9 by deleting it
    	gbp:info: Rolling back branch master by resetting it to ce99782336e83a56e8e579b3cdadf93b0c19e1a8
    	gbp:info: Rolling back failed merge of upstream/1.9
    	gbp:error: Rolled back changes after import error.

In this case the import failed due to a merge conflict. Other reasons are running out of disk space, problems when generating the pristine-tar delta. If you don't want gbp import-orig to undo changes made to the repository use the `--no-rollback`.