gbp import-orig creates a git tag, with default
--upstream-tag=upstream/%(version)s

When used with --uscan, the tag includes any repacking suffix (+dfsg1)
specified in debian/watch. However that works only when the latest
upstream release is pulled via uscan.

Sometimes we need an older release, specified by --upstream-version.
But in the case of a specified version, the +dfsg1 repacking suffix is
dropped, it is not used in gbp's upstream tag.

For instance, trying to package adios2
(https://salsa.debian.org/science-team/adios2) and specifying v2.8.1,
I get:

$ gbp import-orig --uscan -u2.8.1 --verbose
gbp:debug: ['git', 'rev-parse', '--show-cdup']
gbp:debug: ['git', 'rev-parse', '--is-bare-repository']
gbp:debug: ['git', 'rev-parse', '--git-dir']
gbp:debug: ['git', 'for-each-ref', '--format=%(refname:short)', 'refs/heads/']
gbp:debug: ['git', 'show-ref', '--verify', 'refs/heads/upstream']
gbp:debug: ['git', 'status', '--porcelain']
gbp:info: Launching uscan...
Newest version of adios2 on remote site is 2.8.1, specified download version is 2.8.1
Successfully repacked ../adios2-2.8.1.tar.gz as ../adios2_2.8.1+dfsg1.orig.tar.xz, deleting 517 files from itgbp:info: Using uscan downloaded tarball ../adios2_2.8.1+dfsg1.orig.tar.xz
gbp:debug: ['git', 'tag', '-l', 'upstream/2.8.1']
gbp:debug: tar ['-C', '../tmp1zd0cmte', '-a', '-xf', '../adios2_2.8.1+dfsg1.orig.tar.xz'] []
gbp:debug: Unpacked '../adios2_2.8.1+dfsg1.orig.tar.xz' to '../tmp1zd0cmte/ADIOS2-2.8.1'
gbp:info: <DebianUpstreamSource path='../adios2_2.8.1+dfsg1.orig.tar.xz' signaturefile=None>
gbp:info: Importing '../adios2_2.8.1+dfsg1.orig.tar.xz' to branch 'upstream'...
gbp:info: Source package is adios2
gbp:info: Upstream version is 2.8.1
gbp:debug: ['git', 'show-ref', '--verify', 'refs/heads/upstream']
gbp:debug: ['git', 'rev-parse', '--quiet', '--verify', 'upstream']
gbp:debug: ['git', 'add', '-f', '.']
gbp:debug: ['git', 'write-tree']
gbp:debug: ['git', 'rev-parse', '--quiet', '--verify', 'upstream']
gbp:debug: ['git', 'commit-tree', 'b6bd2fec8ddd4682bb7b16f87e57286f93ac0984', '-p', '0d8247511446cb41740f2cbb74ee40943e549e82']
gbp:debug: ['git', 'update-ref', '-m', 'gbp: New upstream version 2.8.1', 'refs/heads/upstream', '687fef9491c76d31f551408e1dfc5fa200405fc3', '0d8247511446cb41740f2cbb74ee40943e549e82']
gbp:debug: ['git', 'tag', '-m', 'Upstream version 2.8.1', '--no-sign', 'upstream/2.8.1', '687fef9491c76d31f551408e1dfc5fa200405fc3']
gbp:debug: ['git', 'show-ref', '--verify', 'refs/heads/master']
gbp:debug: ['git', 'rev-parse', '--quiet', '--verify', 'master']
gbp:debug: ['git', 'show', '--pretty=medium', 'master:debian/source/format']
gbp:debug: 3.0 (quilt) package, replacing debian/ dir
gbp:info: Replacing upstream source on 'master'
gbp:debug: ['git', 'ls-tree', '-z', 'upstream/2.8.1^{tree}', '--']
gbp:debug: ['git', 'ls-tree', '-z', 'master^{tree}', '--']
gbp:debug: Using 98a2d1eddd69b16b3b68b040a0132f9c80ebef39 as debian/ tree
gbp:debug: ['git', 'mktree', '-z']
gbp:debug: ['git', 'commit-tree', '11b6cfd34d89eea0c9c12ac8f1a1f04346f1da5b', '-p', 'master^{commit}', '-p', 'upstream/2.8.1^{commit}']
gbp:debug: ['git', 'update-ref', '-m', 'gbp: Updating master after import of upstream/2.8.1', 'refs/heads/master', 'f687f080be196b7a37375aa561f561d4bd104678']
gbp:debug: ['git', 'symbolic-ref', 'HEAD']
gbp:debug: ['git', 'show-ref', 'refs/heads/master']
gbp:debug: ['git', 'reset', '--quiet', '--hard', 'f687f080be196b7a37375aa561f561d4bd104678', '--']
gbp:debug: ['git', 'symbolic-ref', 'HEAD']
gbp:debug: ['git', 'show-ref', 'refs/heads/master']
gbp:debug: rm ['-rf', '../tmp1zd0cmte'] []
gbp:info: Successfully imported version 2.8.1 of ../adios2_2.8.1+dfsg1.orig.tar.xz
drew@sandy:~/projects/mathlibs/build/adios2$ git tag
upstream/2.5.0+g2020.05.13
upstream/2.5.0+g2020.05.13.1
upstream/2.5.0+g2020.05.13.1+dfsg1
upstream/2.5.0+g2020.05.21+dfsg1
upstream/2.8.1


So the tag is given as upstream/2.8.1 without the +dfsg1 suffix
(but the suffix is used in the orig tarball name)


If I then try to import the latest release (v2.9.1), I get:

$ gbp import-orig --uscan  --verbose
gbp:debug: ['git', 'rev-parse', '--show-cdup']
gbp:debug: ['git', 'rev-parse', '--is-bare-repository']
gbp:debug: ['git', 'rev-parse', '--git-dir']
gbp:debug: ['git', 'for-each-ref', '--format=%(refname:short)', 'refs/heads/']
gbp:debug: ['git', 'show-ref', '--verify', 'refs/heads/upstream']
gbp:debug: ['git', 'status', '--porcelain']
gbp:info: Launching uscan...
Newest version of adios2 on remote site is 2.9.1, local version is 2.5.0+g2020.05.21
       (mangled local version is 2.5.0+g2020.05.21)
 => Newer package available from:
        => https://github.com/ornladios/ADIOS2/archive/refs/tags/v2.9.1.tar.gz
Successfully repacked ../adios2-2.9.1.tar.gz as ../adios2_2.9.1+dfsg1.orig.tar.xz, deleting 517 files from itgbp:info: Using uscan downloaded tarball ../adios2_2.9.1+dfsg1.orig.tar.xz
What is the upstream version? [2.9.1+dfsg1]
gbp:debug: ['git', 'tag', '-l', 'upstream/2.9.1+dfsg1']
gbp:debug: tar ['-C', '../tmps3ajtsuc', '-a', '-xf', '../adios2_2.9.1+dfsg1.orig.tar.xz'] []
gbp:debug: Unpacked '../adios2_2.9.1+dfsg1.orig.tar.xz' to '../tmps3ajtsuc/ADIOS2-2.9.1'
gbp:info: <DebianUpstreamSource path='../adios2_2.9.1+dfsg1.orig.tar.xz' signaturefile=None>
gbp:info: Importing '../adios2_2.9.1+dfsg1.orig.tar.xz' to branch 'upstream'...
gbp:info: Source package is adios2
gbp:info: Upstream version is 2.9.1+dfsg1
gbp:debug: ['git', 'show-ref', '--verify', 'refs/heads/upstream']
gbp:debug: ['git', 'rev-parse', '--quiet', '--verify', 'upstream']
gbp:debug: ['git', 'add', '-f', '.']
gbp:debug: ['git', 'write-tree']
gbp:debug: ['git', 'rev-parse', '--quiet', '--verify', 'upstream']
gbp:debug: ['git', 'commit-tree', 'c997f98b7703842f7a5b042a6f9e2cf94fb0a0d4', '-p', '687fef9491c76d31f551408e1dfc5fa200405fc3']
gbp:debug: ['git', 'update-ref', '-m', 'gbp: New upstream version 2.9.1+dfsg1', 'refs/heads/upstream', '9de477fc47a2a0f9f02445ba5be1fa9dee1148b4', '687fef9491c76d31f551408e1dfc5fa200405fc3']
gbp:debug: ['git', 'tag', '-m', 'Upstream version 2.9.1+dfsg1', '--no-sign', 'upstream/2.9.1+dfsg1', '9de477fc47a2a0f9f02445ba5be1fa9dee1148b4']
gbp:debug: ['git', 'show-ref', '--verify', 'refs/heads/master']
gbp:debug: ['git', 'rev-parse', '--quiet', '--verify', 'master']
gbp:debug: ['git', 'show', '--pretty=medium', 'master:debian/source/format']
gbp:debug: 3.0 (quilt) package, replacing debian/ dir
gbp:info: Replacing upstream source on 'master'
gbp:debug: ['git', 'ls-tree', '-z', 'upstream/2.9.1+dfsg1^{tree}', '--']
gbp:debug: ['git', 'ls-tree', '-z', 'master^{tree}', '--']
gbp:debug: Using 98a2d1eddd69b16b3b68b040a0132f9c80ebef39 as debian/ tree
gbp:debug: ['git', 'mktree', '-z']
gbp:debug: ['git', 'commit-tree', '5722b62676df8747541f571e5c8801dd918cdd57', '-p', 'master^{commit}', '-p', 'upstream/2.9.1+dfsg1^{commit}']
gbp:debug: ['git', 'update-ref', '-m', 'gbp: Updating master after import of upstream/2.9.1+dfsg1', 'refs/heads/master', 'fbfc1ee48288886b5143c4271b22301f5da32448']
gbp:debug: ['git', 'symbolic-ref', 'HEAD']
gbp:debug: ['git', 'show-ref', 'refs/heads/master']
gbp:debug: ['git', 'reset', '--quiet', '--hard', 'fbfc1ee48288886b5143c4271b22301f5da32448', '--']
gbp:debug: ['git', 'symbolic-ref', 'HEAD']
gbp:debug: ['git', 'show-ref', 'refs/heads/master']
gbp:debug: rm ['-rf', '../tmps3ajtsuc'] []
gbp:info: Successfully imported version 2.9.1+dfsg1 of ../adios2_2.9.1+dfsg1.orig.tar.xz
drew@sandy:~/projects/mathlibs/build/adios2$ git tag
upstream/2.5.0+g2020.05.13
upstream/2.5.0+g2020.05.13.1
upstream/2.5.0+g2020.05.13.1+dfsg1
upstream/2.5.0+g2020.05.21+dfsg1
upstream/2.8.1
upstream/2.9.1+dfsg1


So using the same debian/watch file, "gbp import-orig --uscan -u2.8.1"
drops the +dfsg1 suffix in the upstream tag,
while "gbp import-orig --uscan" includes the +dfsg1 suffix in the tag.
The behaviour of gbp import-orig is not consistent.

Hi Drew,

On Sat, 19 Aug 2023 21:18:03 +0200 Drew Parsons <dparsons@debian.org>  wrote:
 > gbp import-orig creates a git tag, with default
 > --upstream-tag=upstream/%(version)s
 >
 > When used with --uscan, the tag includes any repacking suffix (+dfsg1)
 > specified in debian/watch. However that works only when the latest
 > upstream release is pulled via uscan.
 >
 > Sometimes we need an older release, specified by --upstream-version.
 > But in the case of a specified version, the +dfsg1 repacking suffix is
 > dropped, it is not used in gbp's upstream tag.
 >
 > For instance, trying to package adios2
 > (https://salsa.debian.org/science-team/adios2) and specifying v2.8.1,
 > I get:
 >
 > $ gbp import-orig --uscan -u2.8.1 --verbose

I've found this to be quite frustrating too, but I disagree with you
slightly on the solution. Or, at the very least, I can point out some
places where the documentation is confusing. If we check the manpage for
d/watch, it describes Dversion-Mangle [1]:

 > Normalize the last upstream version string found in debian/changelog
to compare it to the available upstream tarball version. Removal of the
Debian specific suffix such as s/@DEB_EXT@// is usually done here.

 From this, my understanding is that the "upstream version string" is
the version string from d/changelog, though it excludes the Debian
portion of the version following the dash. The upstream version thus
includes the +dfsg suffix.

The -u option for gbp import-orig is short for --upstream-version, so
you should be using "gbp import-orig --uscan -u2.8.1+dfsg --verbose".
Or, that would be the case except the gbp import-orig manpage [2]
documents --upstream-version as forwarding the argument directly to
uscan --download-version:

 > --upstream-version=version, -uversion
 >    The upstream version number. With --uscan, passed to uscan as
--download-version

and `uscan --download-version` is documented as [3]:

 > --download-version version
 >     Specify the version which the upstream release must match in
order to be considered, rather than using the release with the highest
version. (a best effort feature)

which we can contrast with uscan --download-debversion, which would do
what we actually want [3]:

 > --download-debversion version
 >     Specify the Debian package version to download the corresponding
upstream release version. The dversionmangle and uversionmangle rules
are considered. (a best effort feature)

To me, the problem really seems to be that `gbp import-orig
--upstream-version` should be calling ` uscan --download-debversion` 
(and documented as such).

As of git-buildpackage 0.9.6, gbp import-orig --uscan --upstream-version
is actually supposed to already be calling `uscan --download-debversion`
if `uscan --download-version` fails. That feature would be sufficient to
fix the weirdness with gbp --uscan --upstream-version and a +dfsg
suffix, but there was a bug in the implementation of the feature [4][5],
and gbp import-orig actually ends up calling uscan without any version
arguments.

If that mistake is fixed, then "gbp import-orig --uscan -u2.8.1+dfsg"
will achieve what you're trying to do. To me, expecting the dfsg suffix
in the upstream version string seems like it would be more consistent
with other related tools. With that said, I'm not an expert on this
terminology.

Sincerely,
Cory Bloor

[1]: https://manpages.debian.org/unstable/devscripts/debian-watch.5.en.html
[2]:
https://manpages.debian.org/unstable/git-buildpackage/gbp-import-orig.1.en.html#upstream
[3]: https://manpages.debian.org/unstable/devscripts/uscan.1.en.html
[4]:
https://salsa.debian.org/agx/git-buildpackage/-/commit/7d509bf8948e66e08b8bdd505b86ac5e4c374eae.patch
[5]: The variables passed for download_debversion are incorrect in the
second and third hunks of [4].

Cordell Bloor wrote:
...


I think I agree with what you're saying.  To pull repacked older
versions we could write

  gbp import-orig --uscan -u2.8.1+dfsg

rather than

  gbp import-orig --uscan -u2.8.1

(reasonable for the latter to not perform repacking, if the former is
available and works)

I note you raised the same issue in Bug#1128260

Bug#1087647 is also related.
Discussion says Bug#1087641 was supposed to deal with the problem in
devscripts, but that has now been done and git-buildpackage is still
not functioning correctly (as in #1128260).