gbp-import-ref(1)

📦
version 0.9.43 · 6 versions
, in ubuntu stonking

gbp-import-ref — the manual page, but make it fashion 💖

okay bestie, so this is gbp-import-ref from the git-buildpackage manual, and it's about to be your new fave. it keeps your upstream sources fresh in a git-only workflow, no tarballs, no drama. let's get into it 🦋

✨ NAME ✨

gbp-import-ref — update upstream sources in a git only workflow

✨ SYNOPSIS ✨

gbp import-ref [--version] [--help] [--verbose] [--color=[auto|on|off]]
               [--color-scheme= COLOR_SCHEME] [--upstream-version=
               version] [--merge-mode= [auto|merge|replace]]
               [--upstream-branch= branch_name] [--upstream-tag=
               tag_format] [--upstream-tree= [BRANCH|VERSION|commit-id]]
               [--debian-branch= branch_name] [--[no-]sign-tags]
               [--keyid= gpg-keyid] [--postimport=cmd] [--[no-]rollback]

look at her. she's serving options. 💅

✨ DESCRIPTION ✨

so gbp import-ref merges upstream git commits onto your debian-branch. that's the whole gig. 🌈

and you've got three whole ways to tell it what to bring in:

  • specify a branch to merge
  • give it an upstream version
  • specify the commit id directly

and here's the lil bonus: if no tag exists for the imported commit, it gets automatically created. no extra steps, we love a self-sufficient queen 👑

✨ OPTIONS ✨

  • --version — prints the version of the program, like, the version of the whole git-buildpackage suite 🎀
  • -v, --verbose — verbose execution. she'll tell you everything she's doing, oversharing era fr fr
  • -h, --help — prints help and exits. classic.
  • --color=[auto|on|off] — whether to use colored output. yes the vibes are configurable 💅
  • --color-scheme=COLOR_SCHEME — the colors to use in output (when color is enabled, obvs). the format for COLOR_SCHEME is '<debug>:<info>:<warning>:<error>'. numerical values and color names are both accepted, and an empty field means "just use the default color, bestie". for example, --git-color-scheme='cyan:34::' would show debug messages in cyan, info messages in blue, and other messages in default — meaning warning and error messages come out in red 🔥
  • --upstream-version=version, -uversion — the upstream version to merge. the upstream tag it uses gets determined via --upstream-tag. so you say the version, she finds the tag, slay.
  • --merge-mode=[auto|merge|replace] — how to fold the upstream commits onto the Debian packaging branch. this one's important, pay attention 🫶
    • merge does a Git merge and leaves 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. it's basically a theirs merge strategy while preserving debian/. iconic behaviour tbh
    • the default is auto, which uses replace for 3.0 (quilt) packages and merge otherwise. she picks for you ✨
  • --upstream-branch=branch_name — the branch in the Git repository where the upstream sources live. default is upstream.
  • --upstream-tag=tag-format — use this tag format when looking up upstream tags. default is upstream/%(version)s.
  • --upstream-tree=[BRANCH|VERSION|commit-id] — what to merge into the debian-branch. BRANCH merges from the upstream branch. VERSION (which is the default) looks for a tag determined from the given upstream version number via the --upstream-version option. any other value gets interpreted as a git commit id to merge from.
  • --debian-branch=branch_name — the branch in the Git repository where the Debian package is being developed. default is master.
  • --[no-]sign-tags — GPG sign all created tags. security, but make it cute 🔐
  • --keyid=gpg-keyid — use this keyid for gpg signing tags.
  • --import-msg=msg-format — use this format string for the commit message when importing upstream versions. default is New upstream version %(version)s. she said write your own but here's a good one.
  • --postimport=cmd — run cmd after the import. the hook gets these environment variables passed to it, so jot them down bestie:
    • 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'
  • --[no-]rollback — rollback changes in case of an error. the "undo" button, the safety net, the parachute 🪂

✨ EXAMPLES ✨

merge commits from the upstream-branch into the debian-branch, creating a tag for the version 0.0~git20180524:

gbp import-ref --upstream-tree=BRANCH -u0.0~git20180524

merge commits from the tag corresponding to version 1.0:

gbp import-ref --upstream-tree=VERSION -u1.0

merge commits given by a SHA1, creating a tag for the version 0.0~git20180524:

gbp import-ref --upstream-tree=c4398912c -u0.0~git20180524

so three examples, three vibes, all valid 😌

✨ CONFIGURATION FILES ✨

several gbp.conf files get parsed to set defaults for all those command-line arguments up there. if you wanna know the deets, go read the gbp.conf(5) manpage. iykyk 📖

✨ 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⟩

the whole friend group, honestly 🫶

✨ AUTHOR ✨

Guido Günther <agx@sigxcpu.org>

ty for your service, king 👑

and that's the page, bestie! this one came from the git-buildpackage Manual, version dated 26 May 2026. go forth and import your refs, you're gonna do amazing 💖✨🎀

📦 where this page comes from