gbp-import-orig(1)

📦
version 0.9.43 · 6 versions
, in ubuntu stonking

✨ gbp-import-orig ✨

okay bestie, this is the page for gbp-import-orig from the git-buildpackage manual. She's a whole queen 💅 and she's about to make importing upstream sources into your git repo actually cute. Let's get into it 🫶

🌸 NAME 🌸

gbp-import-orig — Import an upstream source from tarball, or git tag and tarball, into a git repository 💖

🎀 SYNOPSIS 🎀

gbp import-orig [--version] [--help] [--verbose] [--color=[auto|on|off]]
                [--color-scheme= COLOR_SCHEME] [--upstream-version=
                version] [--[no-]merge] [--merge-mode=
                [auto|merge|replace]] [--upstream-branch= branch_name]
                [--debian-branch= branch_name] [--upstream-vcs-tag= tag-
                format] [--[no-]sign-tags] [--keyid= gpg-keyid]
                [--upstream-tag= tag-format] [--filter= pattern]...
                [--component= component]... [--[no-]pristine-tar]
                [--[no-]filter-pristine-tar] [--[no-]symlink-orig]
                [--postimport=cmd] [--postunpack=cmd]
                [--[no-]interactive] [--[no-]rollback]
                [--upstream-signatures=[auto|on|off]] filename | url |
                --uscan

🦋 DESCRIPTION 🦋

So gbp import-orig imports upstream sources into a Git repository, and optionally links them to upstream's git history. And it can pull from three sources, periodt:

  1. filename: a file sitting on your local file system. Gzip, bzip2, lzma and xz compressed tar archives, zip archives, and already-unpacked source trees are all supported. very giving 💖
  2. url: the tarball gets downloaded from a http or https url. Heads up — this needs the python3-request package installed. no cap.
  3. --uscan: the latest upstream or the version you specify gets fetched via uscan, relying on debian/watch. iconic.

If the tarball's name is already in the form package-name_version.orig.tar.gz, then the version info is determined straight from the tarball's filename. Otherwise you can hand it over on the command line with --upstream-version. And if the source package name or version just can't be figured out, gbp import-orig will prompt for it — unless you gave --no-interactive. 🫶

The sources get placed on the upstream branch (default: upstream), tagged, and merged onto the debian branch (default: master). That happens either using a plain git merge, or by creating a whole new tree that is the new upstream version plus the debian/ directory. The second one is what gets used for source format 3.0 (quilt) packages, because direct modifications of the upstream sources are not allowed in that format, so a 1:1 replacement of the upstream sources is almost always what you want. You can tweak that with --merge-mode. ✨

When you use the --upstream-vcs-tag option, the tag matching the version of the imported release gets added as an additional parent of the commit created for the imported tarball. This ties the upstream git commit history to the Debian packaging history, and it lets you do things like easy cherry-picking of patches and comparing upstream git against the upstream tarball. lowkey genius.

If there's an error, gbp import-orig will rollback (undo) all the changes it has made to the repository (see the --rollback option). it's got your back 😭

Also! For projects using multiple tarballs, the names of the additional components need to be specified via the --component command line option or via gbp.conf (details below, bestie).

💅 OPTIONS 💅

  • --version — Print the version of the program, i.e. the version of the git-buildpackage suite. she's showing off her ID 💖
  • -v, --verbose — Verbose execution. tell me everything, queen.
  • -h, --help — Print help and exit.
  • --color=[auto|on|off] — Whether to use colored output. aesthetic decisions matter ✨
  • --color-scheme=COLOR_SCHEME — Which colors to use in the output (when color is enabled, obviously). The format for COLOR_SCHEME is '<debug>:<info>:<warning>:<error>'. Numerical values and color names are both accepted, and empty fields imply the default color. For example, --git-color-scheme='cyan:34::' would show debug messages in cyan, info messages in blue, and other messages in default (i.e. warning and error messages in red). custom palette, obsessed 🎨
  • --upstream-version=version, -uversion — The upstream version number. With --uscan, it's passed to uscan as --download-version.
  • --[no-]merge — Merge the upstream branch to the Debian branch after import.
  • --merge-mode=[auto|merge|replace] — How to fold the newly imported upstream source into the Debian packaging branch after import.
    • merge does a Git merge, leaving you on your own if there's a merge conflict to resolve. good luck bestie 💀
    • replace mode, on the other hand, makes the head of the Debian packaging branch identical to the newly imported tree, but preserves the content of the debian/ directory while keeping the current head as well as the newly imported tree as parents of the generated commit. This is similar to a theirs merge strategy while preserving debian/. iconic behaviour honestly.
    • The default is auto, which uses replace for 3.0 (quilt) packages and merge otherwise.
  • --upstream-branch=branch_name — The branch in the Git repository the upstream sources are put onto. Default is upstream.
  • --debian-branch=branch_name — The branch in the Git repository the Debian package is being developed on, default is master. After importing the new sources on the upstream branch, gbp import-orig will try to merge the new version onto this branch.
  • --upstream-vcs-tag=tag-format — Add tag-format as an additional parent to the commit of the upstream tarball. Useful when upstream uses git and you want to link to its revision history. The tag-format can be a pattern similar to what --upstream-tag supports.
  • --[no-]sign-tags — GPG sign all created tags. secure her 🔐
  • --keyid=gpg-keyid — Use this keyid for gpg signing tags.
  • --upstream-tag=tag-format — Use this tag format when tagging upstream versions, default is upstream/%(version)s.
  • --import-msg=msg-format — Use this format string for the commit message when importing upstream versions, default is New upstream version %(version)s.
  • --filter=pattern — Filter out files glob-matching pattern. This option can be given multiple times.
  • --component=COMPONENT — When importing the upstream tarball also look for an additional tarball with component name COMPONENT. E.g. in hello-debhelper_1.0.orig-foo.tar.gz the component would be foo. The additional tarball is expected to be in the same directory as the upstream tarball and to use the same compression type. You also need to specify the components when using --uscan.
Using additional original tarballs is a feature of the 3.0 (quilt) source format. See the dpkg-source manpage for details. This is currently considered an experimental feature and might change incompatibly. ⚠️
  • --[no-]pristine-tar — Generate pristine-tar delta file.
  • --[no-]filter-pristine-tar — If using a filter, also filter the files out of the tarball passed to pristine-tar.
  • --[no-]symlink-orig — Whether to create and keep a symlink from the upstream tarball to a Debian policy conformant upstream tarball name located in ../.
This is a good idea if you're not using pristine-tar, since it avoids creating a new tarball with a different md5sum. 🫶
  • --postimport=cmd — Run cmd after the import. The hook gets the following environment variables passed to it:
    • GBP_BRANCH — the name of the Debian packaging branch
    • GBP_TAG — the name of the just created upstream tag
    • GBP_UPSTREAM_VERSION — the just imported upstream version
    • GBP_DEBIAN_VERSION — the Debian version of the package with a Debian revision of '-1'
  • --postunpack=cmd — Run cmd after the import. This can be useful to e.g. convert or remove certain files prior to the import. The hook gets passed the following environment variables:
    • GBP_TMP_DIR — the temporary directory the tarballs are unpacked into.
    • GBP_SOURCES_DIR — the temporary directory where the unpacked sources are.
    • GBP_GIT_DIR — the directory of the git repository where the tarball will be imported into.
  • --uscan — Use uscan to fetch a new upstream version. The version can be specified with --upstream-version. ✨
  • --[no-]interactive — Run command interactively, i.e. ask for the package name and version if needed.
  • --[no-]rollback — Rollback changes in case of an error. the safety net, we love her 😭
  • --upstream-signatures=[auto|on|off] — Whether upstream signatures should be imported as well (when using pristine-tar). off turns this off completely, while on always tries to import a signature (which can be useful if you want it to fail when e.g. uscan did not fetch a signature). The default auto means to import a signature file if present but do nothing otherwise.

🌈 EXAMPLES 🌈

Download and import a new upstream version using the information from debian/watch:

gbp import-orig --uscan

Fetch a tarball from an URL:

gbp import-orig https://debian.example.com/sid/upstream-tarball-0.1.tar.gz

Import a local tarball:

gbp import-orig ../upstream-tarball-0.1.tar.gz

🍓 CONFIGURATION FILES 🍓

Several gbp.conf files get parsed to set defaults for the command-line arguments above. See the gbp.conf(5) manpage for the details, bestie 🫶

👑 SEE ALSO 👑

gbp-buildpackage(1), gbp-import-dsc(1), gbp-import-dscs(1), gbp-dch(1), gbp.conf(5), uscan(1), debuild(1), git(1), pristine-tar(1), The Git-Buildpackage Manual ⟨file:///usr/share/doc/git-buildpackage/manual-html/index.html⟩ 🌸

💖 AUTHOR 💖

Guido Günther <agx@sigxcpu.org> — thank you king 🫡

so yeah, that's the whole page! this was version-of-the-page from the git-buildpackage suite, dated 26 May 2026, and it's gbp-import-orig(1) obviously 💅 go forth and import, bestie. slay. ✨🎀🦋

📦 where this page comes from