[git-buildpackage] gbp push without upstream branch

[Otto Kekäläinen]

Hi Markus!

> I am trying to convert some of Packages to git-buildpackage and am struggling a bit about how to do that
> with an upstream branch.

I am guessing the root cause for your challenge is that the
terminology in git-buildpackage is a bit confusing. The
'upstream-branch' and 'upstream-tag' do not refer to the actual
upstream branch or tag names, but the to the commits done by `gbp
import-orig --uscan` that represent the upstream release contents.

The diagrams in these posts may help understand how git-buildpackage works:

https://optimizedbyotto.com/post/debian-source-package-git/
https://optimizedbyotto.com/post/debian-packaging-from-git/

> I use gbp 0.9.30 any my gbp.conf is
>
> DEFAULT]
> debian-branch = debian/latest
> #upstream-branch = upstream/latest
> pristine-tar = True
> #upstream-vcs-tag = v%(version)s
>
> [git-buildpackage]
> upstream-tag = v%(version)s

You should not customize `upstream-tag` at all, and the reason you
should customize `upstream-branch` to be `debian/latest` is simply
because the branch name git-buildpackage uses by default does not
adhere to DEP-14, and you should be adhering to it.


What I recommend you do here is:

1. Make sure your debian/watch file points to the location the
upstream release tarball can be downloaded from so that uscan always
works. You should not manually bypass it with `gbp import-ref` even
though git-buildpackage has this option (see
https://lists.debian.org/debian-devel/2026/01/msg00148.html for longer
explanation). Current
https://salsa.debian.org/science-team/dune-common/-/blob/debian/latest/debian/watch
probably needs a bit fine tuning, and using uupdate is perhaps not
that optimal now that `gbp-dch` exists and it can update the
debian/changelog in a much better way.

2. Make sure your `debian/upstream/metadata` tells git-buildpackage
where the upstream git is. This seems to be correct now in
https://salsa.debian.org/science-team/dune-common/-/blob/debian/latest/debian/upstream/metadata#L3.
Running `gbp clone --upstreamvcs
git at salsa.debian.org:science-team/dune-common.git` will automatically
add a remote called `upstreamvcs` which is needed to fetch commits
from upstream.

3. Make sure your `debian/gbp.conf` has this:

[DEFAULT]
# DEP-14 format. Other naming convention are available,
# see DEP-14 for more details.
debian-branch = debian/latest
upstream-branch = upstream/latest

# Enable pristine-tar to exactly reproduce orig tarballs
pristine-tar = True

# The Debian packaging git repository may also host actual upstream tags and
# branches, typically named 'main' or 'master'. Configure the upstream tag
# format below, so that `gbp import-orig` will run correctly, and link tarball
# import branch (`upstream/latest`) with the equivalent upstream release tag,
# showing a complete audit trail of what upstream released and what was imported
# into Debian.
upstream-vcs-tag = v%(version%~%.)s


I've checked the upstream tags at
https://gitlab.dune-project.org/core/dune-common/-/tags that the above
line is correct.

With this config when you run `gbp import-orig --uscan` everything
will work correctly, and the upstream git tag will be fetched, merged
to upstream/latest, reconclined with upstream tarball contents and
merged on debian/latest branch contents. You can run `git blame` on
any upstream file to see why upstream changed something and you can
easily rebase patche queue branches and cherry-pick patches to new
branches to submit upstream etc.

For the package where some files need to be removed from upstream you
should have the exact same config, but the files to be excluded in
debian/copyright:Files-Excluded. You import always with `gbp
import-orig --uscan` and uscan will automatically filter out those
files and rename the source package with +ds1 etc and everything is
correct automatically.

You got some extra tips from Guido on how to manually do special
things, but I suspect you actually were asking about best practices
and how to do things in a consistent and automated way. Doing subtasks
of the import manually is possible, but you easily get into a state
where the software provenance chaing is broken or your git repo
contents becomes incompatible with various tools, so it is better to
stick to standard DEP-14 layout and standard workflows and not do
extra manual tricks.

- Otto