--- name: "gbp-buildpackage" section: "1" platform: "linux" package: "git-buildpackage" version: "0.9.38" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/gbp-buildpackage" --- # gbp-buildpackage(1) Build Debian source and binary packages from a Git repository ## NAME gbp-buildpackage - Build Debian source and binary packages from a Git repository ## SYNOPSIS FC**gbp buildpackage**F\[0\] \[FC**--git-\[no-\]ignore-new**F\[0\]\] \[FC**--git-tag**F\[0\]\] \[FC**--git-verbose**F\[0\]\] \[FC**--git-color=**F\[0\]\[auto\|on\|off\]\] \[FC**--git-color-scheme**F\[0\]= *COLOR\_SCHEME*\] \[FC**--git-notify=**F\[0\]\[auto\|on\|off\]\] \[FC**--git-upstream-branch=**F\[0\] *TREEISH*\] \[FC**--git-debian-branch=**F\[0\] *BRANCH\_NAME*\] \[FC**--git-ignore-branch**F\[0\]\] \[FC**--git-\[no-\]submodules**F\[0\]\] \[FC**--git-builder=**F\[0\] *BUILD\_CMD*\] \[FC**--git-cleaner=**F\[0\] *CLEAN\_CMD*\] \[FC**--git-\[no-\]overlay**F\[0\]\] \[FC**--git-\[no-\]pbuilder**F\[0\]\] \[FC**--git-\[no-\]qemubuilder**F\[0\]\] \[FC**--git-dist=**F\[0\] *DIST*\] \[FC**--git-arch=**F\[0\] *ARCH*\] \[FC**--git-\[no-\]pbuilder-autoconf**F\[0\]\] \[FC**--git-pbuilder-options**F\[0\]= *PBUILDER\_OPTIONS*\] \[FC**--git-\[no-\]sign-tags**F\[0\]\] \[FC**--git-keyid=**F\[0\] *GPG-KEYID*\] \[FC**--git-preexport=**F\[0\] *COMMAND*\] \[FC**--git-postexport=**F\[0\] *COMMAND*\] \[FC**--git-prebuild=**F\[0\] *COMMAND*\] \[FC**--git-postbuild=**F\[0\] *COMMAND*\] \[FC**--git-posttag=**F\[0\] *COMMAND*\] \[FC**--git-\[no-\]hooks**F\[0\]\] \[FC**--git-debian-tag=**F\[0\] *tag-format*\] \[FC**--git-debian-tag-msg=**F\[0\] *tag-msg-format*\] \[FC**--git-upstream-tag=**F\[0\] *tag-format*\] \[FC**--git-force-create**F\[0\]\] \[FC**--git-no-create-orig**F\[0\]\] \[FC**--git-upstream-signatures=**F\[0\]\[auto\|on\|off\]\] \[FC**--git-upstream-tree=**F\[0\] *\[BRANCH\|SLOPPY\|TAG\|TREEISH\]*\] \[FC**--git-tarball-dir=**F\[0\] *DIRECTORY*\] \[FC**--git-compression=**F\[0\] *TYPE*\] \[FC**--git-compression-level=**F\[0\] *LEVEL*\] \[FC**--git-component=**F\[0\] *component*\]... \[FC**--git-export-dir=**F\[0\] *DIRECTORY*\] \[FC**--git-export=**F\[0\] *TREEISH*\] \[FC**--git-\[no-\]pristine-tar**F\[0\]\] \[FC**--git-\[no-\]pristine-tar-commit**F\[0\]\] \[FC**--git-\[no-\]-purge**F\[0\]\] \[FC**--git-tag-only**F\[0\]\] \[FC**--git-retag**F\[0\]\] \[FC**OPTION\_PASSED\_TO\_BUILD\_CMD**F\[0\]\]... ## DESCRIPTION **gbp buildpackage** is used to build Debian source and .deb packages from a Git repository. For a complete description of concepts, git repository layout and recommended workflows, see the online manual at https://gbp.sigxcpu.org/manual/ **gbp buildpackage** will, in order: - • Verify that it is being executed from the proper location. - • Verify that the repository doesn't contain any uncommitted source changes. - • Verify that it is being executed from the correct branch. - • (Optionally) run a clean command specified with FC**--git-cleaner**F\[0\]. - • (Optionally) export the source tree to a separate build area. - • Build an orig tarball if it doesn't exist. Optionally using pristine-tar. - • (Optionally) call a pre build hook. - • Call [debuild(1)](/debuild/1.md) or Cowbuilder (via FC**--git-pbuilder**F\[0\]) or the application specified via FC**--git-builder**F\[0\] passing along all arguments given to **gbp buildpackage** on the command line that don't start with --git-. - • (Optionally) tag the current commit after a successful build. - • (Optionally) call a post build hook - e.g. to run **lintian**. - • (Optionally) call a post tag hook - e.g. to push the results to a remote repository after creating the tag. ## OPTIONS All options are prefixed with FC**git-**F\[0\] to distinguish options for **gbp buildpackage** from options passed to the *BUILD\_CMD*: ### UPSTREAM TARBALL CREATION OPTIONS When **gbp buildpackage** doesn't find a suitable upstream tarball it will create one either using pristine-tar or **git archive**. These options determine how the tarball is created: - FC**--git-pristine-tar**F\[0\] Use pristine-tar when generating the upstream tarball if it doesn't exist. If this mode is enabled the FC**--git-upstream-tag**F\[0\], FC**--git-upstream-tree**F\[0\] options have no effect when creating tarballs. - FC**--git-upstream-tag=**F\[0\]*TAG-FORMAT* Use this tag format when looking for tags of upstream versions to build the upstream tarballs. Default is *upstream/%(version)s*. This must be set correctly if you don't want to pass any other options. The default matches what **gbp import-orig** uses to create tags. - FC**--git-upstream-tree=**F\[0\]*\[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 given via the FC**--git-upstream-branch**F\[0\] option. The *SLOPPY* option looks at the debian branch given via the FC**--git-debian-branch**F\[0\] and drops the FC*debian/*F\[0\] dir. Other values are interpreted as treeishs. This doesn't have any effect if FC**--git-pristine-tar**F\[0\] is being used. - FC**--git-upstream-branch**F\[0\]=*BRANCH\_NAME* Branch to build the orig tarball from if FC**--git-upstream-tree**F\[0\] is set to *BRANCH*. Default is *upstream*. - FC**--git-tarball-dir=**F\[0\]*DIRECTORY* Search for upstream tarballs in *DIRECTORY* instead of generating them. If a tarball is not found here it will be generated nevertheless. *DIRECTORY* can contain a version format substitution pattern, eg: *foo-%(version)s*. - FC**--git-component=**F\[0\]*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 details. Note that the *--git-pristine-tar-commit* option is currently incompatible with this option. This is considered an experimental feature and might change incompatibly. - FC**--git-pristine-tar-commit**F\[0\] 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. - FC**--git-force-create**F\[0\] Force creation of an upstream tarball (overwriting a pre-existing one if present). - FC**--git-no-create-orig**F\[0\] Don't try to create any upstream tarballs or to create symlinks to existing tarballs in FC**tarball-dir**F\[0\]. - FC**--git-upstream-signatures=**F\[0\]\[auto\|on\|off\] Whether to export the upstream tarball with signatures. - FC**--git-\[no-\]submodules**F\[0\] Include Git submodules in the orig tarball if present. - FC**--git-compression=**F\[0\]*TYPE* Specifies the upstream tarball compression type. This will be 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*. - FC**--git-compression-level=**F\[0\]*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 determine which builder is invoked and how. - FC**--git-builder=**F\[0\]*BUILD\_CMD* Use *BUILD\_CMD* instead of **debuild -i -I**. If you want to use Cowbuilder or Pbuilder see the FC**--git-pbuilder**F\[0\]. - FC**--git-cleaner=**F\[0\]*CLEAN\_CMD* Use *CLEAN\_CMD* to clean the source tree before the build. The default is **/bin/true** (no cleaning). - FC**--git-pbuilder**F\[0\] Build the package using **git-pbuilder** (which uses **cowbuilder** by default). Note that this overwrites any FC**--git-builder**F\[0\] and FC**--git-cleaner**F\[0\] options. - FC**--git-qemubuilder**F\[0\] Build package using **git-pbuilder** with **qemubuilder**. Note that this overwrites any FC**--git-builder**F\[0\] and FC**--git-cleaner**F\[0\] options. - FC**--git-dist=**F\[0\]*DIST* Build for distribution *DIST* when using **git-pbuilder** (either via FC**--git-pbuilder**F\[0\], FC**--git-qemubuilder**F\[0\] or the corresponding configuration file options). If unset build for the unstable distribution. The special value FCDEP-14F\[0\] will set the distribution to build for from the branch name. I.e. if you're starting the build from a branch named *debian/wheezy-backports* the distribution is set to *wheezy-backports* or if the branch is named *debian/12-bookworm* the distribution is set to *bookworm* (the numeric prefix is stripped). If the branch is named *downstream/sid* the distribution is set to *downstream\_sid*. - FC**--git-arch=**F\[0\]*ARCH* Build for architecture *ARCH* when using **git-pbuilder** (either via FC**--git-pbuilder**F\[0\], FC**--git-qemubuilder**F\[0\] or the corresponding configuration file options). If unset no architecture is passed to **git-pbuilder**. - FC**--git-pbuilder-autoconf**F\[0\] 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** (either via FC**--git-pbuilder**F\[0\], FC**--git-qemubuilder**F\[0\] or the corresponding configuration file options). - FC**--git-pbuilder-options**F\[0\] Options to pass to pbuilder when building via **git-pbuilder** (either via FC**--git-pbuilder**F\[0\], FC**--git-qemubuilder**F\[0\] or the corresponding configuration file options). It does so by using the **GIT\_PBUILDER\_OPTIONS** environment variable to pass options to **git-pbuilder**. As an example, to tell pbuilder to use an alternate .pbuilderrc file, you may run **gbp buildpackage** with FC**--git-pbuilder-options=**F\[0\]*"--configfile* */tmp/my/pbuilderrc"*. See [**pbuilder**(8)](/pbuilder/8.md) for more options to pass through here. If unset the **GIT\_PBUILDER\_OPTIONS** environment variable will be left untouched. - FC**--git-notify=**F\[0\]\[auto\|on\|off\] Whether to send a desktop notification after the build. This needs python3-notify2 installed. ### HOOK OPTIONS Hooks allow you to run arbitrary commands at different stages of the build. These options configure what will be run: - FC**--git-preexport=**F\[0\]*COMMAND* Execute *COMMAND* before exporting the source tree. Valid only if --git-export-dir has been specified. Exported environment variables are: **GBP\_GIT\_DIR** (the repository the package is being built from), **GBP\_BUILD\_DIR** (the build dir). - FC**--git-postexport=**F\[0\]*COMMAND* Execute *COMMAND* after exporting the source tree. Valid only if --git-export-dir has been specified. The working directory of this hook is the toplevel directory of the exported source tree. Exported environment variables are: **GBP\_GIT\_DIR** (the repository the package is being built from), **GBP\_TMP\_DIR** (the temporary directory where the sources have been initially exported). - FC**--git-prebuild=**F\[0\]*COMMAND* Execute *COMMAND* from the build directory before calling debuild or the application specified via FC**--git-builder**F\[0\]. Exported environment variables are: **GBP\_GIT\_DIR** (the repository the package is being built from), **GBP\_BUILD\_DIR** (the build dir). - FC**--git-postbuild=**F\[0\]*COMMAND* Execute *COMMAND* after successful build. The working directory of this hook is the directory the package was built in. Exported environment variables are: **GBP\_CHANGES\_FILE** (the name of the generated changes file), **GBP\_BUILD\_DIR** (the build dir). - FC**--git-posttag=**F\[0\]*COMMAND* Execute *COMMAND* after tagging a new version. The working directory of this hook is the toplevel directory of the Git repository. Exported environment variables 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). - FC**--git-\[no-\]hooks**F\[0\] Enable running all (cleaner, preexport, postexport, prebuild, postbuild, and posttag) hooks. Note: the FC**--git-builder**F\[0\] command is not affected by this option. ### TAGGING OPTIONS - FC**--git-tag**F\[0\] Add 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 is tagged. This is a command line only option that cannot be specified via FC*gbp.conf*F\[0\]. - FC**--git-\[no-\]sign-tags**F\[0\] GPG sign all created tags. - FC**--git-keyid=**F\[0\]*GPG-KEYID* Use this keyid for gpg signing tags. - FC**--git-debian-tag=**F\[0\]*TAG-FORMAT* Use this tag format when tagging Debian versions, default is *debian/%(version)s*. - FC**--git-debian-tag-msg=**F\[0\]*tag-msg-format* Use this tag message format when signing Debian versions, default is *%(pkg)s Debian release %(version)s* - FC**--git-retag**F\[0\] Don'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 FC*gbp.conf*F\[0\]. - FC**--git-tag-only**F\[0\] Don't build, only tag and run post-tag hooks. This is a command line only option that cannot be specified via FC*gbp.conf*F\[0\]. ### BUILD AREA OPTIONS **gbp buildpackage** can export the source tree to a different build-area before performing the build. This options specify if and how this is done: - FC**--git-export-dir=**F\[0\]*DIRECTORY* Export the current branch head (or the treeish object given via FC**--git-export**F\[0\] to *DIRECTORY* before building. If unset the source will not be exported before starting the build. - FC**--git-export=**F\[0\]*TREEISH* Instead of exporting the current branch head, export the treeish object *TREEISH*. The special name *INDEX* exports the current index whereas the special name *WC* exports the current working copy as is. Note that using *WC* enables the FC**--git-ignore-branch**F\[0\] and FC**--git-ignore-new**F\[0\] options as well since when exporting the working copy there's no point in enforcing any branch or modification checks. - FC**--git\[-no\]-purge**F\[0\] Purge (remove) temporary build area after build. This is the default but it can be turned off for e.g. debugging purposes. - FC**--git-\[no-\]overlay**F\[0\] Extract upstream tarball from FC**tarball-dir**F\[0\] when using the FC**export-dir**F\[0\] option (in analogy to mergeWithUpstream in svn-bp). Also remove debian/ if contained in the upstream tarball in case of 2.0 and 3.0 source formats. This option allows one to keep only the debian/ dir in the version control system. ### SAFETY OPTIONS In order to make sure what you build is what you upload **gbp buildpackage** performs several safety checks. These options allow one to configure and disable them: - FC**--git-debian-branch**F\[0\]=*BRANCH\_NAME* If you're not on this branch when invoking **gbp buildpackage** it will fail. Default is *master*. This is done to make sure you don't accidentally release from a topic branch. Not being on this branch will be ignored when using FC**--git-ignore-new**F\[0\]. - FC**--git-ignore-branch**F\[0\] Don't check if the current branch matches *DEBIAN-BRANCH*. - FC**--git-\[no-\]ignore-new**F\[0\] Don't abort if there are uncommitted changes in the source tree or the current branch doesn't match the *DEBIAN-BRANCH*. ### COLOR AND VERBOSITY OPTIONS - FC**--git-verbose**F\[0\] Verbose execution. Useful for debugging and bug reports. - FC**--git-color=**F\[0\]\[auto\|on\|off\] Whether to use colored output. - FC**--git-color-scheme**F\[0\]=*COLOR\_SCHEME* Colors to use in output (when color is enabled). The format for COLOR\_SCHEME is '\:\:\:\'. Numerical values and color names are accepted, 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 will run **debuild** in current directory: ``` FC gbp buildpackage F[0] ``` Build a source-only package that can be signed and uploaded to Debian: ``` FC gbp buildpackage -S -d F[0] ``` Build a Debian package using **git-pbuilder** which in turn invokes **cowbuilder**. Instruct cowbuilder to build within a Wheezy chroot for i386. ``` FC gbp buildpackage --git-pbuilder --git-arch=i386 --git-dist=wheezy F[0] ``` Note that the above needs a **cowbuilder** chroot already. This can be created using: ``` FC DIST=wheezy ARCH=i386 git-pbuilder create F[0] ``` To export the source tree without performing any build you can use: ``` FC gbp buildpackage --git-export-dir=/where/to/export --git-builder=/bin/true --git-no-pbuilder --git-no-hooks --git-no-purge F[0] ``` ## CONFIGURATION FILES Several FC*gbp.conf*F\[0\] files are parsed to set defaults for the above command-line arguments. See the [**gbp.conf**(5)](/gbp.conf/5.md) manpage for details. All options in the config files must be specified without the 'git-' prefix. So e.g. FC**--git-debian-branch**F\[0\]=*debian/latest* becomes in FC*gbp.conf*F\[0\]: ``` FC [buildpackage] debian-branch = debian/latest F[0] ``` ## SEE ALSO [**gbp-import-dsc**(1)](/gbp-import-dsc/1.md), [**gbp-import-dscs**(1)](/gbp-import-dscs/1.md), [**gbp-import-orig**(1)](/gbp-import-orig/1.md), [**gbp-dch**(1)](/gbp-dch/1.md), [**git-pbuilder**(1)](/git-pbuilder/1.md), [**cowbuilder**(8)](/cowbuilder/8.md), [**dpkg-source**(1)](/dpkg-source/1.md), [**git-submodule**(1)](/git-submodule/1.md), [**gbp.conf**(5)](/gbp.conf/5.md), [**debuild**(1)](/debuild/1.md), [**git**(1)](/git/1.md), [**pristine-tar**(1)](/pristine-tar/1.md),\ The Git-Buildpackage Manual ⟨file:///usr/share/doc/git-buildpackage/manual-html/index.html⟩ ## AUTHOR Guido Günther \