diff options
author | Guido Günther <agx@sigxcpu.org> | 2017-08-04 19:44:48 -0300 |
---|---|---|
committer | Guido Günther <agx@sigxcpu.org> | 2017-08-04 20:20:36 -0300 |
commit | e7bbd6523fbb68ce69be1be7ebbd231ab9f6ea36 (patch) | |
tree | b6f368e067d9f8da0454b5cd7337e59c988cb0e9 | |
parent | 4424008f6aaa7ce93d02f0c4948ad50542284ece (diff) |
gbp-buildpackage: Group manpage options
Closes: #824801
-rw-r--r-- | docs/manpages/gbp-buildpackage.sgml | 1213 |
1 files changed, 638 insertions, 575 deletions
diff --git a/docs/manpages/gbp-buildpackage.sgml b/docs/manpages/gbp-buildpackage.sgml index 63b285ef..8a9c33ab 100644 --- a/docs/manpages/gbp-buildpackage.sgml +++ b/docs/manpages/gbp-buildpackage.sgml @@ -44,8 +44,8 @@ <arg><option>--git-prebuild=</option><replaceable>COMMAND</replaceable></arg> <arg><option>--git-[no-]hooks</option></arg> <arg><option>--git-debian-tag=</option><replaceable>tag-format</replaceable></arg> - <arg><option>--git-upstream-tag=</option><replaceable>tag-format</replaceable></arg> <arg><option>--git-debian-tag-msg=</option><replaceable>tag-msg-format</replaceable></arg> + <arg><option>--git-upstream-tag=</option><replaceable>tag-format</replaceable></arg> <arg><option>--git-force-create</option></arg> <arg><option>--git-no-create-orig</option></arg> <arg><option>--git-upstream-tree=</option><replaceable>[TAG|BRANCH|TREEISH]</replaceable></arg> @@ -58,7 +58,6 @@ <arg><option>--git-[no-]pristine-tar</option></arg> <arg><option>--git-[no-]pristine-tar-commit</option></arg> <arg><option>--git-[no-]-purge</option></arg> - <arg><option>--git-dont-purge</option></arg> <arg><option>--git-tag-only</option></arg> <arg><option>--git-retag</option></arg> <arg rep="repeat"><option>OPTION_PASSED_TO_BUILD_CMD</option></arg> @@ -67,27 +66,27 @@ <refsect1> <title>DESCRIPTION</title> <para> - &gbp-buildpackage; is used to build &debian; source and .deb packages from - a &git; repository. + &gbp-buildpackage; is used to build &debian; source and .deb packages from + a &git; repository. </para> <para> - &gbp-buildpackage; will, in order: + &gbp-buildpackage; will, in order: </para> <itemizedlist> <listitem> <para> - Verify that it is being executed from the proper location. + Verify that it is being executed from the proper location. </para> </listitem> <listitem> <para> - Verify that the repository doesn't contain any uncommitted source - changes. + Verify that the repository doesn't contain any uncommitted source + changes. </para> </listitem> <listitem> <para> - Verify that it is being executed from the correct branch. + Verify that it is being executed from the correct branch. </para> </listitem> <listitem> @@ -98,12 +97,12 @@ </listitem> <listitem> <para> - (Optionally) export the source tree to a separate build area. + (Optionally) export the source tree to a separate build area. </para> </listitem> <listitem> <para> - Build an orig tarball if it doesn't exist. Optionally using &pristine-tar;. + Build an orig tarball if it doesn't exist. Optionally using &pristine-tar;. </para> </listitem> <listitem> @@ -122,18 +121,18 @@ </listitem> <listitem> <para> - (Optionally) tag the current commit after a successful build. + (Optionally) tag the current commit after a successful build. </para> </listitem> <listitem> <para> - (Optionally) call a post build hook - e.g. to run &lintian;. + (Optionally) call a post build hook - e.g. to run &lintian;. </para> </listitem> <listitem> <para> - (Optionally) call a post tag hook - e.g. to push the results to a - remote repository after creating the tag. + (Optionally) call a post tag hook - e.g. to push the results to a + remote repository after creating the tag. </para> </listitem> </itemizedlist> @@ -145,561 +144,621 @@ distinguish options for &gbp-buildpackage; from options passed to the <replaceable>BUILD_CMD</replaceable>: </para> - <variablelist> - <varlistentry> - <term><option>--git-[no-]ignore-new</option> - </term> - <listitem> - <para> - Don't abort if there are uncommitted changes in the source tree or - the current branch doesn't match the - <replaceable>DEBIAN-BRANCH</replaceable>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-tag</option> - </term> - <listitem> - <para> - Add a git tag after a successful build. It tags the - currently checked out commmit except when you're on a - patch-queue branch. In that case the corresponding debian - branch is tagged. - </para> - <para> - This is a command line only option that cannot be - specified via &gbp.conf;. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-builder=<replaceable>BUILD_CMD</replaceable></option> - </term> - <listitem> - <para> - Use <replaceable>BUILD_CMD</replaceable> instead of - <command>debuild -i -I</command>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-cleaner=<replaceable>CLEAN_CMD</replaceable></option> - </term> - <listitem> - <para> - Use <replaceable>CLEAN_CMD</replaceable> to clean the - source tree before the build. The default - is <command>/bin/true</command>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-pbuilder</option> - </term> - <listitem> - <para> - Build package using <command>git-pbuilder</command> (which - uses <command>cowbuilder</command> by default). Note that this overwrites - any <option>--git-builder</option> and - <option>--git-cleaner</option> options. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-qemubuilder</option> - </term> - <listitem> - <para> - Build package using <command>git-pbuilder</command> with - <command>qemubuilder</command>. Note that this overwrites any - <option>--git-builder</option> and <option>--git-cleaner</option> - options. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-dist=<replaceable>DIST</replaceable></option> - </term> - <listitem> - <para> - Build for distribution <replaceable>DIST</replaceable> - when using &git-pbuilder; (either - via <option>--git-pbuilder</option>, <option>--git-qemubuilder</option> - or the corresponding configuration file options). If - unset build for the unstable distribution. The special - value <symbol>DEP14</symbol> will set the distribution to - build for from the branch name. I.e. if you're starting - the build from a branch named - <replaceable>debian/wheezy-backports</replaceable> the - distribution is set - to <replaceable>wheezy-backports</replaceable>. If the - branch is named <replaceable>downstream/sid</replaceable> - the distribution would be set - to <replaceable>downstream_sid</replaceable>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-arch=<replaceable>ARCH</replaceable></option> - </term> - <listitem> - <para> - Build for architecture <replaceable>ARCH</replaceable> - when using &git-pbuilder; (either - via <option>--git-pbuilder</option>, <option>--git-qemubuilder</option> - or the corresponding configuration file options). If - unset no architecture is passed - to <command>git-pbuilder</command>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-pbuilder-autoconf</option> - </term> - <listitem> - <para> - 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 <option>--git-pbuilder</option>, <option>--git-qemubuilder</option> - or the corresponding configuration file options). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-pbuilder-options</option> - </term> - <listitem> - <para> - Options to pass to pbuilder when building via &git-pbuilder; (either - via <option>--git-pbuilder</option>, <option>--git-qemubuilder</option> - or the corresponding configuration file options). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-verbose</option> - </term> - <listitem> - <para> - verbose execution - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-color=</option>[auto|on|off] - </term> - <listitem> - <para> - Whether to use colored output. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-notify=</option>[auto|on|off] - </term> - <listitem> - <para> - Whether to send a desktop notification after the build. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-color-scheme</option>=<replaceable>COLOR_SCHEME</replaceable> - </term> - <listitem> - <para> - 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 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). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-upstream-branch</option>=<replaceable>BRANCH_NAME</replaceable> - </term> - <listitem> - <para> - Branch to build the orig tarball from if - <option>--git-upstream-tree</option> is set to - <replaceable>BRANCH</replaceable>. Default is - <replaceable>upstream</replaceable>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-debian-branch</option>=<replaceable>BRANCH_NAME</replaceable> - </term> - <listitem> - <para> - If you're not on this branch when invoking &gbp-buildpackage; it will - fail. Default is <replaceable>master</replaceable>. 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 - <option>--git-ignore-new</option>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-ignore-branch</option> - </term> - <listitem> - <para> - Don't check if the current branch matches - <replaceable>DEBIAN-BRANCH</replaceable>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-[no-]sign-tags</option> - </term> - <listitem> - <para> - GPG sign all created tags. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-[no-]submodules</option> - </term> - <listitem> - <para> - Include git submodules in the orig tarball. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-keyid=</option><replaceable>GPG-KEYID</replaceable> - </term> - <listitem> - <para> - Use this keyid for gpg signing tags. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-posttag=</option><replaceable>COMMAND</replaceable> - </term> - <listitem> - <para> - Execute <replaceable>COMMAND</replaceable> after tagging a new - version. - </para> - <para> - Exported environment variables are: <envar>GBP_TAG</envar> (the name - of the generated tag), <envar>GBP_BRANCH</envar> (the branch the - package was build from) and <envar>GBP_SHA1</envar> (the sha1 of the - commit the tag was created at). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-postbuild=</option><replaceable>COMMAND</replaceable> - </term> - <listitem> - <para> - Execute <replaceable>COMMAND</replaceable> after successful - build. - </para> - <para> - Exported environment variables are: <envar>GBP_CHANGES_FILE</envar> - (the name of the generated changes file), - <envar>GBP_BUILD_DIR</envar> (the build dir). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-postexport=</option><replaceable>COMMAND</replaceable> - </term> - <listitem> - <para> - Execute <replaceable>COMMAND</replaceable> after exporting the source - tree - valid only if --git-export-dir has been specified. - </para> - <para> - Exported environment variables are: <envar>GBP_GIT_DIR</envar> (the - repository the package is being built from), - <envar>GBP_TMP_DIR</envar> (the temporary directory where the sources - have been initially exported). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-prebuild=</option><replaceable>COMMAND</replaceable> - </term> - <listitem> - <para> - Execute <replaceable>COMMAND</replaceable> from the build directory - before calling <application>debuild</application> or the application - specified via <option>--git-builder</option>. - </para> - <para> - Exported environment variables are: <envar>GBP_GIT_DIR</envar> (the - repository the package is being built from), - <envar>GBP_BUILD_DIR</envar> (the build dir). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-[no-]hooks</option> - </term> - <listitem> - <para> - Enable running all (cleaner, postexport, prebuild, postbuild, and - posttag) hooks. Note: the <option>--git-builder</option> command is - not affected by this option. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-debian-tag=</option><replaceable>TAG-FORMAT</replaceable> - </term> - <listitem> - <para> - Use this tag format when tagging &debian; versions, default is - <replaceable>debian/%(version)s</replaceable>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-upstream-tag=</option><replaceable>TAG-FORMAT</replaceable> - </term> - <listitem> - <para> - Use this tag format when looking for tags of upstream versions, - default is <replaceable>upstream/%(version)s</replaceable>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-debian-tag-msg=</option><replaceable>tag-msg-format</replaceable> - </term> - <listitem> - <para>Use this tag message format when signing &debian; versions, - default is <replaceable>%(pkg)s Debian release %(version)s</replaceable></para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-force-create</option> - </term> - <listitem> - <para> - Force creation of an orig tarball (overwriting a pre-existing one if - present). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-no-create-orig</option> - </term> - <listitem> - <para> - Don't try to create any orig tarball. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-overlay</option> - </term> - <listitem> - <para> - Extract orig tarball from <option>tarball-dir</option> when - using the <option>export-dir</option> 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. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-export-dir=</option><replaceable>DIRECTORY</replaceable> - </term> - <listitem> - <para> - Export the current branch head (or the treeish object given via - <option>--git-export</option> to <replaceable>DIRECTORY</replaceable> - before building. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-export=</option><replaceable>TREEISH</replaceable> - </term> - <listitem> - <para> - Instead of exporting the current branch head, export the treeish - object <replaceable>TREEISH</replaceable>. The special name - <replaceable>INDEX</replaceable> exports the current index whereas - the special name <replaceable>WC</replaceable> exports the current - working copy as is. - </para> - <para> - Note that using <replaceable>WC</replaceable> enables the - <option>--git-ignore-branch</option> - and <option>--git-ignore-new</option> options as well - since when exporting the working copy there's no point in - enforcing any branch or modification checks. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-upstream-tree=</option><replaceable>[BRANCH|SLOPPY|TAG|TREEISH]</replaceable> - </term> - <listitem> - <para> - How to find the upstream sources used to generate the tarball. - <replaceable>TAG</replaceable> (the default) looks at a tag corresponding to the - version in the changelog. <replaceable>BRANCH</replaceable> looks at - the upstream branch given via the - <option>--git-upstream-branch</option> option. The <replaceable>SLOPPY</replaceable> - option looks at the debian branch given via - the <option>--git-debian-branch</option> and drops - the <filename>debian/</filename> dir. - </para> - <para> - Other values are interpreted as treeishs. - </para> - <para> - This doesn't have any effect if <option>--git-pristine-tar</option> - is being used. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-tarball-dir=</option><replaceable>DIRECTORY</replaceable> - </term> - <listitem> - <para> - Search for original tarballs in <replaceable>DIRECTORY</replaceable> - instead of generating them. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-compression=</option><replaceable>TYPE</replaceable> - </term> - <listitem> - <para> - Specifies the upstream tarball compression type. This will be used to - locate and build the upstream tarball if necessary. The default is - <replaceable>auto</replaceable> which derives the compression type - from the pristine-tar branch if available and falls back to gzip - otherwise. Other options are <replaceable>gzip</replaceable>, - <replaceable>bzip2</replaceable>, <replaceable>lzma</replaceable> and - <replaceable>xz</replaceable>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-compression-level=</option><replaceable>LEVEL</replaceable> - </term> - <listitem> - <para> - Specifies the upstream tarball compression level if an upstream - tarball needs to be built. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-component=</option><replaceable>COMPONENT</replaceable> - </term> - <listitem> - <para> - When generating tarballs create an additional original - tarball of directory <replaceable>COMPONENT</replaceable> - in the source tree. Using additional original tarballs is - a feature of the 3.0 (quilt) source format. See - the <command>dpkg-source</command> manpage for details. Note that the - <replaceable>--git-pristine-tar-commit</replaceable> - option is currently incompatible with this option. + <refsect2> + <title>Upstream tarball creation options</title> + <para>When &gbp-buildpackage; doesn't find a suitable upstream + tarball it will create one either using &pristine-tar; + or <command>git archive</command>. These options determine how the tarball is created: + </para> + <variablelist> + <varlistentry> + <term><option>--git-pristine-tar</option> + </term> + <listitem> + <para> + Use pristine-tar when generating the upstream tarball if + it doesn't exist. If this mode is enabled + the <option>--git-upstream-tag</option>, <option>--git-upstream-tree</option> + options have no effect. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-upstream-tag=</option><replaceable>TAG-FORMAT</replaceable> + </term> + <listitem> + <para> + Use this tag format when looking for tags of upstream + versions to build the upstream tarballs. Default + is <replaceable>upstream/%(version)s</replaceable>. 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-upstream-tree=</option><replaceable>[BRANCH|SLOPPY|TAG|TREEISH]</replaceable> + </term> + <listitem> + <para> + How to find the upstream sources used to generate the tarball. + <replaceable>TAG</replaceable> (the default) looks at a tag corresponding to the + version in the changelog. <replaceable>BRANCH</replaceable> looks at + the upstream branch given via the + <option>--git-upstream-branch</option> option. The <replaceable>SLOPPY</replaceable> + option looks at the debian branch given via + the <option>--git-debian-branch</option> and drops + the <filename>debian/</filename> dir. + </para> + <para> + Other values are interpreted as treeishs. + </para> + <para> + This doesn't have any effect if <option>--git-pristine-tar</option> + is being used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-upstream-branch</option>=<replaceable>BRANCH_NAME</replaceable> + </term> + <listitem> + <para> + Branch to build the orig tarball from if + <option>--git-upstream-tree</option> is set to + <replaceable>BRANCH</replaceable>. Default is + <replaceable>upstream</replaceable>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-tarball-dir=</option><replaceable>DIRECTORY</replaceable> + </term> + <listitem> + <para> + Search for upstream tarballs in <replaceable>DIRECTORY</replaceable> + instead of generating them. If a tarball is not found here it + will be generated nevertheless. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-component=</option><replaceable>COMPONENT</replaceable> + </term> + <listitem> + <para> + When generating tarballs create an additional upstream + tarball of directory <replaceable>COMPONENT</replaceable> + in the source tree. Using additional upstream tarballs is + a feature of the 3.0 (quilt) source format. See + the <command>dpkg-source</command> manpage for details. Note that the + <replaceable>--git-pristine-tar-commit</replaceable> + option is currently incompatible with this option. </para> <para> This is considered an experimental feature and might change incompatibly. </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git[-no]-purge</option> - </term> - <listitem> - <para> - Purge (remove) temporary build directory after build. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-dont-purge</option> - </term> - <listitem> - <para> - Deprecated, use --git-no-purge instead. This is a command line only option - that cannot be specified via &gbp.conf;. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-tag-only</option> - </term> - <listitem> - <para> - Don't build, only tag and run post-tag hooks. This is a - command line only option that cannot be specified via - &gbp.conf;. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-retag</option> - </term> - <listitem> - <para> - 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 &gbp.conf;. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-pristine-tar</option> - </term> - <listitem> - <para> - Use pristine-tar when generating the upstream tarball if it doesn't - exist. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--git-pristine-tar-commit</option> - </term> - <listitem> - <para> - 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. - </para> - </listitem> - </varlistentry> - </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-pristine-tar-commit</option> + </term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-force-create</option> + </term> + <listitem> + <para> + Force creation of an upstream tarball (overwriting a pre-existing one if + present). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-no-create-orig</option> + </term> + <listitem> + <para> + Don't try to create any upstream tarballs. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-[no-]submodules</option> + </term> + <listitem> + <para> + Include &git; submodules in the orig tarball if present. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-compression=</option><replaceable>TYPE</replaceable> + </term> + <listitem> + <para> + Specifies the upstream tarball compression type. This will be used to + locate and build the upstream tarball if necessary. The default is + <replaceable>auto</replaceable> which derives the compression type + from the pristine-tar branch if available and falls back to gzip + otherwise. Other options are <replaceable>gzip</replaceable>, + <replaceable>bzip2</replaceable>, <replaceable>lzma</replaceable> and + <replaceable>xz</replaceable>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-compression-level=</option><replaceable>LEVEL</replaceable> + </term> + <listitem> + <para> + Specifies the upstream tarball compression level if an upstream + tarball needs to be built. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2> + <title>Package build options</title> + <para>&gbp-buildpackage; can invoke different types of builders + to produce the source and binary packages. These options + determine which builder is invoked and how. + </para> + <variablelist> + <varlistentry> + <term><option>--git-builder=<replaceable>BUILD_CMD</replaceable></option> + </term> + <listitem> + <para> + Use <replaceable>BUILD_CMD</replaceable> instead of + <command>debuild -i -I</command>. If you want to use + &cowbuilder; or &pbuilder; see + the <option>--git-pbuilder</option>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-cleaner=<replaceable>CLEAN_CMD</replaceable></option> + </term> + <listitem> + <para> + Use <replaceable>CLEAN_CMD</replaceable> to clean the + source tree before the build. The default + is <command>/bin/true</command> (no cleaning). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-pbuilder</option> + </term> + <listitem> + <para> + Build the package using <command>git-pbuilder</command> (which + uses <command>cowbuilder</command> by default). Note that this overwrites + any <option>--git-builder</option> and + <option>--git-cleaner</option> options. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-qemubuilder</option> + </term> + <listitem> + <para> + Build package using <command>git-pbuilder</command> with + <command>qemubuilder</command>. Note that this overwrites any + <option>--git-builder</option> and <option>--git-cleaner</option> + options. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-dist=<replaceable>DIST</replaceable></option> + </term> + <listitem> + <para> + Build for distribution <replaceable>DIST</replaceable> + when using &git-pbuilder; (either + via <option>--git-pbuilder</option>, <option>--git-qemubuilder</option> + or the corresponding configuration file options). If + unset build for the unstable distribution. The special + value <symbol>DEP14</symbol> will set the distribution to + build for from the branch name. I.e. if you're starting + the build from a branch named + <replaceable>debian/wheezy-backports</replaceable> the + distribution is set + to <replaceable>wheezy-backports</replaceable>. If the + branch is named <replaceable>downstream/sid</replaceable> + the distribution is set + to <replaceable>downstream_sid</replaceable>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-arch=<replaceable>ARCH</replaceable></option> + </term> + <listitem> + <para> + Build for architecture <replaceable>ARCH</replaceable> + when using &git-pbuilder; (either + via <option>--git-pbuilder</option>, <option>--git-qemubuilder</option> + or the corresponding configuration file options). If + unset no architecture is passed + to <command>git-pbuilder</command>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-pbuilder-autoconf</option> + </term> + <listitem> + <para> + 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 <option>--git-pbuilder</option>, <option>--git-qemubuilder</option> + or the corresponding configuration file options). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-pbuilder-options</option> + </term> + <listitem> + <para> + Options to pass to pbuilder when building via &git-pbuilder; (either + via <option>--git-pbuilder</option>, <option>--git-qemubuilder</option> + or the corresponding configuration file options). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-notify=</option>[auto|on|off] + </term> + <listitem> + <para> + Whether to send a desktop notification after the + build. This needs python3-notify2 installed. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2> + <title>Hook options</title> + <para> + Hooks allow to run arbitrary commands at different stages of the + build. These options configure what will be run: + </para> + <variablelist> + <varlistentry> + <term><option>--git-posttag=</option><replaceable>COMMAND</replaceable> + </term> + <listitem> + <para> + Execute <replaceable>COMMAND</replaceable> after tagging a new + version. + </para> + <para> + Exported environment variables are: <envar>GBP_TAG</envar> (the name + of the generated tag), <envar>GBP_BRANCH</envar> (the branch the + package was build from) and <envar>GBP_SHA1</envar> (the sha1 of the + commit the tag was created at). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-postbuild=</option><replaceable>COMMAND</replaceable> + </term> + <listitem> + <para> + Execute <replaceable>COMMAND</replaceable> after successful + build. + </para> + <para> + Exported environment variables are: <envar>GBP_CHANGES_FILE</envar> + (the name of the generated changes file), + <envar>GBP_BUILD_DIR</envar> (the build dir). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-postexport=</option><replaceable>COMMAND</replaceable> + </term> + <listitem> + <para> + Execute <replaceable>COMMAND</replaceable> after exporting the source + tree - valid only if --git-export-dir has been specified. + </para> + <para> + Exported environment variables are: <envar>GBP_GIT_DIR</envar> (the + repository the package is being built from), + <envar>GBP_TMP_DIR</envar> (the temporary directory where the sources + have been initially exported). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-prebuild=</option><replaceable>COMMAND</replaceable> + </term> + <listitem> + <para> + Execute <replaceable>COMMAND</replaceable> from the build directory + before calling <application>debuild</application> or the application + specified via <option>--git-builder</option>. + </para> + <para> + Exported environment variables are: <envar>GBP_GIT_DIR</envar> (the + repository the package is being built from), + <envar>GBP_BUILD_DIR</envar> (the build dir). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-[no-]hooks</option> + </term> + <listitem> + <para> + Enable running all (cleaner, postexport, prebuild, postbuild, and + posttag) hooks. Note: the <option>--git-builder</option> command is + not affected by this option. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2> + <title>Tagging options</title> + <variablelist> + <varlistentry> + <term><option>--git-tag</option> + </term> + <listitem> + <para> + 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. + </para> + <para> + This is a command line only option that cannot be + specified via &gbp.conf;. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-[no-]sign-tags</option> + </term> + <listitem> + <para> + GPG sign all created tags. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-keyid=</option><replaceable>GPG-KEYID</replaceable> + </term> + <listitem> + <para> + Use this keyid for gpg signing tags. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-debian-tag=</option><replaceable>TAG-FORMAT</replaceable> + </term> + <listitem> + <para> + Use this tag format when tagging &debian; versions, default is + <replaceable>debian/%(version)s</replaceable>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-debian-tag-msg=</option><replaceable>tag-msg-format</replaceable> + </term> + <listitem> + <para>Use this tag message format when signing &debian; versions, + default is <replaceable>%(pkg)s Debian release %(version)s</replaceable></para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-retag</option> + </term> + <listitem> + <para> + 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 &gbp.conf;. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-tag-only</option> + </term> + <listitem> + <para> + Don't build, only tag and run post-tag hooks. This is a + command line only option that cannot be specified via + &gbp.conf;. + </para> + </listitem> + </variablelist> + </refsect2> + <refsect2> + <title>Build area options</title> + <para> + &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: + </para> + <variablelist> + <varlistentry> + <term><option>--git-export-dir=</option><replaceable>DIRECTORY</replaceable> + </term> + <listitem> + <para> + Export the current branch head (or the treeish object given via + <option>--git-export</option> to <replaceable>DIRECTORY</replaceable> + before building. If unset the source will not be + exported before starting the build. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-export=</option><replaceable>TREEISH</replaceable> + </term> + <listitem> + <para> + Instead of exporting the current branch head, export the treeish + object <replaceable>TREEISH</replaceable>. The special name + <replaceable>INDEX</replaceable> exports the current index whereas + the special name <replaceable>WC</replaceable> exports the current + working copy as is. + </para> + <para> + Note that using <replaceable>WC</replaceable> enables the + <option>--git-ignore-branch</option> + and <option>--git-ignore-new</option> options as well + since when exporting the working copy there's no point in + enforcing any branch or modification checks. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git[-no]-purge</option> + </term> + <listitem> + <para> + Purge (remove) temporary build area after build. This is + the default but it can be turned off for e.g. debugging + purposes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-overlay</option> + </term> + <listitem> + <para> + Extract upstream tarball from <option>tarball-dir</option> when + using the <option>export-dir</option> 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. + </para> + <para> + This optios allows to keep only the debian/ dir in the version + control system. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2> + <title>Safety options</title> + <para> + In order to make sure what you build is what you upload + &gbp-buildpackage; performs several safety checks. These options allow to configure and disable them: + </para> + <variablelist> + <varlistentry> + <term><option>--git-debian-branch</option>=<replaceable>BRANCH_NAME</replaceable> + </term> + <listitem> + <para> + If you're not on this branch when invoking &gbp-buildpackage; it will + fail. Default is <replaceable>master</replaceable>. 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 + <option>--git-ignore-new</option>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-ignore-branch</option> + </term> + <listitem> + <para> + Don't check if the current branch matches + <replaceable>DEBIAN-BRANCH</replaceable>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-[no-]ignore-new</option> + </term> + <listitem> + <para> + Don't abort if there are uncommitted changes in the source tree or + the current branch doesn't match the + <replaceable>DEBIAN-BRANCH</replaceable>. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2> + <title>Color and verbosity options</title> + <variablelist> + <varlistentry> + <term><option>--git-verbose</option> + </term> + <listitem> + <para> + Verbose execution. Useful for debugging and bug reports. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-color=</option>[auto|on|off] + </term> + <listitem> + <para> + Whether to use colored output. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--git-color-scheme</option>=<replaceable>COLOR_SCHEME</replaceable> + </term> + <listitem> + <para> + 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 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). + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> </refsect1> <refsect1> <title>EXAMPLES</title> <para> - Build a &debian; package using &git-pbuilder; which in turn invokes - &cowbuildercmd;. Instruct cowbuilder to build within a Wheezy chroot for - i386. + Build a &debian; package using &git-pbuilder; which in turn invokes + &cowbuildercmd;. Instruct cowbuilder to build within a Wheezy chroot for + i386. </para> <screen> &gbp-buildpackage; --git-pbuilder --git-arch=i386 --git-dist=wheezy </screen> <para> - Note that the above needs a &cowbuildercmd; chroot already. This can be - created using: + Note that the above needs a &cowbuildercmd; chroot already. This can be + created using: </para> <screen> DIST=wheezy ARCH=i386 &git-pbuilder; create @@ -721,30 +780,34 @@ <refsect1> <title>SEE ALSO</title> <para> - <xref linkend="man.gbp.import.dsc"/>, - <xref linkend="man.gbp.import.dscs"/>, - <xref linkend="man.gbp.import.orig"/>, - <xref linkend="man.gbp.dch"/>, - <citerefentry> - <refentrytitle>git-pbuilder</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry>, - <citerefentry> - <refentrytitle>cowbuilder</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, - <citerefentry> - <refentrytitle>dpkg-source</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry>, - <xref linkend="man.gbp.conf"/>, - &man.seealso.common; + <xref linkend="man.gbp.import.dsc"/>, + <xref linkend="man.gbp.import.dscs"/>, + <xref linkend="man.gbp.import.orig"/>, + <xref linkend="man.gbp.dch"/>, + <citerefentry> + <refentrytitle>git-pbuilder</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>cowbuilder</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>dpkg-source</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>git-submodule</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, + <xref linkend="man.gbp.conf"/>, + &man.seealso.common; </para> </refsect1> <refsect1> <title>AUTHOR</title> <para> - &dhusername; &dhemail; + &dhusername; &dhemail; </para> </refsect1> </refentry> |