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.