## When upstream uses Git

If upstream uses Git for development (and you don't want to ignore that fact entirely), there are at least three ways to handle packaging. The first one uses Git exclusively and creates the upstream tarballs from the upstream tag while the second one still uses upstream tarballs but links your packaging Git history with upstreams Git history. The third one also uses a tarballs but does not link to the upstream history.

### No upstream tarballs

If upstream doesn't build upstream tarballs, or you don't care about them, the simplest way is to clone upstream's repository and create a separate packaging branch in there. You will not need gbp import-orig at all with this workflow. gbp buildpackage will handle creating the upstream tarballs needed for the Debian source package.

For that to work you need to tell gbp what the upstream tag format looks like. Therefore you either use the `--git-upstream-tag` command line option or the `upstream-tag` configuration file variable to specify upstream's tag format.

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

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

`version` will be replaced by gbp with the upstream version number as determined from `debian/changelog`. The `%()s` might be familiar from Python format strings. The option was placed in the [DEFAULT] section instead of the [buildpackage] section of the configuration so other tools like gbp dch make use of it too.

Some upstreams use other formats though and don't separate numbers by dots but rather by underscore(`_`), hyphen(`-`) or anything else. In order to cope with that you can use version mangling of these characters via substitution. The substitution works as follows:

    [DEFAULT]
    upstream-tag = v%(version%.%_)s

This means that each occurrence of `.` will be replaced by `_` in the upstream version number. For example the upstream version `1.2.3` as determined from the `debian/changelog` will be looked up as Git tag `v1_2_3` by gbp buildpackage.

If you want the substitution to be the `%` character you have to escape it. E.g. `%(version%-%\%)s` will replace `-` with `%`, transforming `1-A.B.C` to `1%A.B.C`. Only a single replacement is supported and it can only replace a single character.

Since some of the possible mangling characters like `_` and `%` are also used to denote epochs and tilde revisions these versions can't be reconstructed when mapping from Git tags back to Debian™ versions and will therefore break other tools like gbp dch. So use version mangling with care. It's better to come up with a Debian compatible tag format upstream. See DEP-14 for the currently used expansion rules for Debian version numbers.

If you're using pristine-tar you can make gbp buildpackage commit the generated tarball back to the pristine-tar branch using the `--git-pristine-tar-commit` option or you can use gbp pristine-tar after you've created the tarballs. This will make sure others building your package can exactly regenerate the tarball you created when building the Debian™ package.

#### 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 ambiguities between the Debian™ packaging repository and the upstream repository, we name the upstream repository `upstream` instead of the default `origin`.

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

The above makes sure we have `debian/latest` 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. We started the branch at the commit corresponding to the tag `v1.0`.

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/latest

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 upstreamvcs
      git merge v1.1
      gbp dch --debian-branch=debian/latest --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 hadn't commit the changelog yet, we need to tell gbp buildpackage that the working directory is unclean via the `--git-ignore-new` option. Once everything looks good, commit the changelog and build a release version:

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

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

### Upstream tarballs and linked upstream history

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.

### Upstream tarballs and separate upstream history

If you want to have upstream's Git history available but don't want to link it to your packaging history you can simply keep it as a separate history. E.g. if you already have a Git repository with your packaging, change into that repository and do:

     git remote add upstreamvcs https://upstream.example.com/upstream.git
     git fetch upstreamvcs

This will pull in upstream's Git history into your repo but since your packaging commits and upstreams commits have no common parents the two histories will stay nicely separated. Of course you can browse it and cherry-pick from it but any remote repos you push to will not get upstream's history by default unless you push any of upstream's refs.

Since Git has a single tag namespace pushing changes with git push --tags will push upstream's tags (and therefore it's history) too so be sure to only push dedicated tag names.