gbp-buildpackage(1)

📦
version 0.9.43 · 6 versions
, in ubuntu stonking

💖 gbp-buildpackage 💖

okay bestie, so this is gbp-buildpackage(1), and it's a page straight out of the git-buildpackage Manual. It's long, it's iconic, it's giving main character energy, and we're doing part 1 right now. Strap in. 🎀

✨ NAME ✨

gbp-buildpackage — build Debian source and binary packages from a Git repository 🦋

✨ SYNOPSIS ✨

gbp buildpackage [--git-[no-]ignore-new] [--git-tag] [--git-verbose]
                 [--git-color=[auto|on|off]] [--git-color-scheme=
                 COLOR_SCHEME] [--git-notify=[auto|on|off]]
                 [--git-upstream-branch= TREEISH] [--git-debian-branch=
                 BRANCH_NAME] [--git-ignore-branch]
                 [--git-[no-]submodules] [--git-builder= BUILD_CMD]
                 [--git-cleaner= CLEAN_CMD] [--git-[no-]overlay]
                 [--git-[no-]pbuilder] [--git-[no-]qemubuilder]
                 [--git-dist= DIST] [--git-arch= ARCH]
                 [--git-[no-]pbuilder-autoconf] [--git-pbuilder-options=
                 PBUILDER_OPTIONS] [--git-[no-]sign-tags] [--git-keyid=
                 GPG-KEYID] [--git-preexport= COMMAND]
                 [--git-postexport= COMMAND] [--git-prebuild= COMMAND]
                 [--git-postbuild= COMMAND] [--git-posttag= COMMAND]
                 [--git-[no-]hooks] [--git-debian-tag= tag-format]
                 [--git-debian-tag-msg= tag-msg-format]
                 [--git-upstream-tag= tag-format] [--git-force-create]
                 [--git-no-create-orig]
                 [--git-upstream-signatures=[auto|on|off]]
                 [--git-upstream-tree= [BRANCH|SLOPPY|TAG|TREEISH]]
                 [--git-tarball-dir= DIRECTORY] [--git-compression=
                 TYPE] [--git-compression-level= LEVEL]
                 [--git-component= component]... [--git-export-dir=
                 DIRECTORY] [--git-export= TREEISH]
                 [--git-[no-]pristine-tar]
                 [--git-[no-]pristine-tar-commit] [--git-[no-]-purge]
                 [--git-tag-only] [--git-retag]
                 [OPTION_PASSED_TO_BUILD_CMD]...

like. look at all of those. slay. 💅

✨ DESCRIPTION ✨

so <hotpink>gbp buildpackage</hotpink> is the whole vibe: it builds Debian source packages and .deb packages straight out of a Git repo, no cap. 🫶

and if you want the full lore — concepts, how the git repo should be laid out, the recommended workflows, all of it — the online manual lives at https://gbp.sigxcpu.org/manual/. go read it, iykyk.

here's the thing: gbp buildpackage is very much a girl with a plan. she does all of this, in this exact order, every time:

  1. verifies she's being run from the right place — vibe check on the location, basically. ✅
  2. verifies the repository has no uncommitted source changes (messy working tree? not in this house). 🚫
  3. verifies she's on the correct branch (yes, the right one). 🌿
  4. optionally runs a clean command, if you gave her one via --git-cleaner.
  5. optionally exports the source tree to a separate build area.
  6. builds an orig tarball if one doesn't already exist — and optionally she'll do it using pristine-tar.
  7. optionally calls a pre build hook.
  8. calls debuild(1) — or Cowbuilder (via --git-pbuilder) — or literally any application you specify with --git-builder, and passes along all the arguments you gave to gbp buildpackage on the command line that don't start with --git-.
  9. optionally tags the current commit after a successful build 🏷️
  10. optionally calls a post build hook — like, say, to run lintian.
  11. optionally calls a post tag hook — e.g. to push the results to a remote repository once the tag is created. 🚀

✨ OPTIONS ✨

okay so every single option is prefixed with git-, and that's on purpose: it's how we tell gbp buildpackage's options apart from the options you're passing through to the BUILD_CMD. genius, honestly.

🌸 UPSTREAM TARBALL CREATION OPTIONS 🌸

when gbp buildpackage can't find a suitable upstream tarball, she will simply make one — either using pristine-tar or git archive. these options decide how that tarball gets made:

  • --git-pristine-tar — use pristine-tar when generating the upstream tarball, if it doesn't already exist. heads up bestie: if this mode is enabled, the --git-upstream-tag and --git-upstream-tree options have no effect when creating tarballs. 😭
  • --git-upstream-tag=TAG-FORMAT — use this tag format when looking for tags of upstream versions, so she can build the upstream tarballs. default is upstream/%(version)s. you must set this correctly if you don't want to pass any other options. the default matches what gbp import-orig uses to create tags, so it all lines up. ✨
  • --git-upstream-tree=[BRANCH|SLOPPY|TAG|TREEISH] — how to find the upstream sources used to generate the tarball. TAG (the default) looks at a tag corresponding to the version in the changelog. BRANCH looks at the upstream branch you gave via the --git-upstream-branch option. SLOPPY looks at the debian branch given via --git-debian-branch and drops the debian/ dir. any other values are interpreted as treeishs. this has no effect at all if --git-pristine-tar is being used. 🤷
  • --git-upstream-branch=BRANCH_NAME — the branch to build the orig tarball from, when --git-upstream-tree is set to BRANCH. default is upstream. 🌿
  • --git-tarball-dir=DIRECTORY — search for upstream tarballs in DIRECTORY instead of generating them. and if a tarball isn't found there? she generates it anyway, she's flexible like that. DIRECTORY can contain a version format substitution pattern, eg: foo-%(version)s. 🍓
  • --git-component=COMPONENT — when generating tarballs, create an additional upstream tarball of directory COMPONENT in the source tree. using additional upstream tarballs is a feature of the 3.0 (quilt) source format — see the dpkg-source manpage for the details. note that the --git-pristine-tar-commit option is currently incompatible with this one. 💀 this is considered an experimental feature and might change incompatibly. proceed accordingly.
  • --git-pristine-tar-commit — commit the pristine-tar delta to the pristine-tar branch, if a new tarball was generated and the pristine-tar data isn't already there.
  • --git-force-create — force creation of an upstream tarball, overwriting a pre-existing one if there is one. (yes, she'll just. do it.) 🔥
  • --git-no-create-orig — don't try to create any upstream tarballs, and don't create symlinks to existing tarballs in tarball-dir. just no. 🙈
  • --git-upstream-signatures=[auto|on|off] — whether to export the upstream tarball with signatures.
  • --git-[no-]submodules — include Git submodules in the orig tarball, if present. 🧚
  • --git-compression=TYPE — specifies the upstream tarball compression type. this gets used to locate and build the upstream tarball if necessary. the default is auto, which derives the compression type from the pristine-tar branch if available, and falls back to gzip otherwise. other options are gzip, bzip2, lzma and xz.
  • --git-compression-level=LEVEL — specifies the upstream tarball compression level, if an upstream tarball needs to be built.

👑 PACKAGE BUILD OPTIONS 👑

gbp buildpackage can invoke different types of builders to produce the source and binary packages. these options decide which builder gets summoned and how:

  • --git-builder=BUILD_CMD — use BUILD_CMD instead of debuild -i -I. wanna use Cowbuilder or Pbuilder? see --git-pbuilder. 💅
  • --git-cleaner=CLEAN_CMD — use CLEAN_CMD to clean the source tree before the build. the default is /bin/true (which is to say: no cleaning at all, she's not gonna pretend).
  • --git-pbuilder — build the package using git-pbuilder (which uses cowbuilder by default). ⚠️ note that this overwrites any --git-builder and --git-cleaner options.
  • --git-qemubuilder — build the package using git-pbuilder with qemubuilder. ⚠️ note that this overwrites any --git-builder and --git-cleaner options too.
  • --git-dist=DIST — build for distribution DIST when using git-pbuilder (whether via --git-pbuilder, --git-qemubuilder, or the corresponding configuration file options). if it's unset, she builds for the unstable distribution. the special value DEP-14 sets the distribution to build for from the branch name — so if you start the build from a branch named debian/wheezy-backports, the distribution is set to wheezy-backports. if the branch is named debian/12-bookworm, the distribution is set to bookworm (the numeric prefix gets stripped ✂️). and if the branch is named downstream/sid, the distribution is set to downstream_sid. she's clever like that.
  • --git-arch=ARCH — build for architecture ARCH when using git-pbuilder (again: via --git-pbuilder, --git-qemubuilder, or the corresponding configuration file options). if unset, no architecture gets passed to git-pbuilder at all.
  • --git-pbuilder-autoconf — whether to try to autoconfigure git-pbuilder, or to rely on the settings in .pbuilderrc. see the git-pbuilder manpage for details. only takes effect when using git-pbuilder (via --git-pbuilder, --git-qemubuilder, or the corresponding configuration file options).
  • --git-pbuilder-options — options to pass to pbuilder when building via git-pbuilder (via --git-pbuilder, --git-qemubuilder, or the corresponding configuration file options). it does this by using the GIT_PBUILDER_OPTIONS environment variable to pass options on to git-pbuilder.

as an example, to tell pbuilder to use an alternate .pbuilderrc file, you may run gbp buildpackage with --git-pbuilder-options="--configfile /tmp/my/pbuilderrc". see pbuilder(8) for more options you can pass through here.

if unset, the GIT_PBUILDER_OPTIONS environment variable will be left untouched. 🫶

  • --git-notify=[auto|on|off] — whether to send a desktop notification after the build. 🔔 this one needs python3-notify2 installed.

🎀 HOOK OPTIONS 🎀

hooks let you run arbitrary commands at different stages of the build — like little side quests. these options configure what gets run:

  • --git-preexport=COMMAND — execute COMMAND before exporting the source tree. only valid if --git-export-dir has been specified.

the exported environment variables are: GBP_GIT_DIR (the repository the package is being built from), and GBP_BUILD_DIR (the build dir). ✨

  • --git-postexport=COMMAND — execute COMMAND after exporting the source tree. only valid if --git-export-dir has been specified. the working directory of this hook is the toplevel directory of the exported source tree.

the exported environment variables are: GBP_GIT_DIR (the repository the package is being built from), and GBP_TMP_DIR (the temporary directory where the sources have been initially exported). 🌈

  • --git-prebuild=COMMAND — execute COMMAND from the build directory, before calling debuild or the application specified via --git-builder.

the exported environment variables are: GBP_GIT_DIR (the repository the package is being built from), and GBP_BUILD_DIR (the build dir). 💜

  • --git-postbuild=COMMAND — runs COMMAND once the build has succeeded 🎉. This hook's working directory is the directory the package was actually built in.

The environment variables it exports for you are: GBP_CHANGES_FILE (the name of the generated changes file) and GBP_BUILD_DIR (the build dir).

  • --git-posttag=COMMAND — runs COMMAND right after a new version gets tagged 💖. This hook's working directory is the toplevel directory of the Git repository.

The environment variables it exports are: GBP_TAG (the name of the generated tag), GBP_BRANCH (the branch the package was built from) and GBP_SHA1 (the sha1 of the commit the tag was created at).

  • --git-[no-]hooks — turns on running all the hooks: cleaner, preexport, postexport, prebuild, postbuild, and posttag. Heads up though — the --git-builder command is not affected by this option, bestie, so don't go thinking it is.

🏷️ TAGGING OPTIONS 🏷️

  • --git-tag — adds a git tag after a successful build ✨. It tags the currently checked out commit, except when you're on a patch-queue branch — in that case the corresponding debian branch gets tagged instead.

This is a command line only option that cannot be specified via gbp.conf 🙈.

  • --git-[no-]sign-tags — GPG sign all created tags 🔏.
  • --git-keyid=GPG-KEYID — use this keyid for gpg signing tags.
  • --git-debian-tag=TAG-FORMAT — use this tag format when tagging Debian versions. The default is debian/%(version)s 💅.
  • --git-debian-tag-msg=tag-msg-format — use this tag message format when signing Debian versions. The default is %(pkg)s Debian release %(version)s.
  • --git-retag — doesn't fail tag operations if a tag with the same version already exists 👑. This is a command line only option that cannot be specified via gbp.conf.
  • --git-tag-only — don't build at all, only tag and run post-tag hooks 🏷️. This is a command line only option that cannot be specified via gbp.conf.

📦 BUILD AREA OPTIONS 📦

gbp buildpackage can export the source tree to a different build-area before it does the actual build. These options specify if and how that happens:

  • --git-export-dir=DIRECTORY — export the current branch head (or the treeish object you gave via --git-export) to DIRECTORY before building 🌸. If you leave it unset, the source will not be exported before the build starts.
  • --git-export=TREEISH — instead of exporting the current branch head, export the treeish object TREEISH. The special name INDEX exports the current index, while the special name WC exports the current working copy as is 👀.

Ok so important note: using WC also enables the --git-ignore-branch and --git-ignore-new options, because when you're exporting the working copy there's literally no point in enforcing any branch or modification checks 💀.

  • --git[-no]-purge — purge (remove) the temporary build area after the build. This is the default 🧹, but you can turn it off for stuff like debugging purposes.
  • --git-[no-]overlay — extract the upstream tarball from tarball-dir when using the export-dir option (in analogy to mergeWithUpstream in svn-bp). It also removes debian/ if that's contained in the upstream tarball, in the case of 2.0 and 3.0 source formats.

This option lets you keep only the debian/ dir in the version control system ✨.

🛟 SAFETY OPTIONS 🛟

To make sure that what you build is what you upload, gbp buildpackage performs several safety checks 😌. These options let you configure them and disable them:

  • --git-debian-branch=BRANCH_NAME — if you're not on this branch when you invoke gbp buildpackage, it will fail. Default is master. This exists so you don't accidentally release from a topic branch 🙈. Not being on this branch will be ignored when using --git-ignore-new.
  • --git-ignore-branch — don't check if the current branch matches DEBIAN-BRANCH.
  • --git-[no-]ignore-new — don't abort if there are uncommitted changes in the source tree, or if the current branch doesn't match the DEBIAN-BRANCH 💅.

🌈 COLOR AND VERBOSITY OPTIONS 🌈

  • --git-verbose — verbose execution. Lowkey useful for debugging and bug reports 🐛.
  • --git-color=[auto|on|off] — whether to use colored output 🎀.
  • --git-color-scheme=COLOR_SCHEME — the colors to use in output (when color is enabled). 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 🔥.

💖 EXAMPLES 💖

Build a package without passing any arguments, simply using package specific options from debian/gbp.conf and user scpecific options from ~/.gbp.conf (if any). By default this will run debuild in the current directory:

gbp buildpackage

Build a source-only package that can be signed and uploaded to Debian:

gbp buildpackage -S -d

Build a Debian package using git-pbuilder, which in turn invokes cowbuilder. Instruct cowbuilder to build within a Wheezy chroot for i386:

gbp buildpackage --git-pbuilder --git-arch=i386 --git-dist=wheezy
Note that the above needs a cowbuilder chroot already 👀. This can be created using:
DIST=wheezy ARCH=i386 git-pbuilder create

To export the source tree without performing any build you can use:

gbp buildpackage --git-export-dir=/where/to/export --git-builder=/bin/true --git-no-pbuilder --git-no-hooks --git-no-purge

📝 CONFIGURATION FILES 📝

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

All options in the config files must be specified without the git- prefix, bestie. So for example, --git-debian-branch=debian/latest becomes in gbp.conf:

[buildpackage]
debian-branch = debian/latest

👀 SEE ALSO 👀

gbp-import-dsc(1), gbp-import-dscs(1), gbp-import-orig(1), gbp-dch(1), git-pbuilder(1), cowbuilder(8), dpkg-source(1), git-submodule(1), gbp.conf(5), 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>

And that's the whole page, bestie!! 💅 This was gbp-buildpackage(1) from version 26 May 2026 — go forth and build, tag, and slay, no cap 🦋✨🎀

📦 where this page comes from