debian_git-buildpackage/docs/manpages/gbp-buildpackage.sgml

<refentry id="man.gbp.buildpackage">
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
  </refentryinfo>
  <refmeta><refentrytitle>gbp-buildpackage</refentrytitle>
    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>gbp-buildpackage</refname>
    <refpurpose>Build &debian; packages from a &git; repository</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      &gbp-buildpackage;
      <arg><option>--git-[no-]ignore-new</option></arg>
      <arg><option>--git-tag</option></arg>
      <arg><option>--git-verbose</option></arg>
      <arg><option>--git-color=</option><replaceable>[auto|on|off]</replaceable></arg>
      <arg><option>--git-color-scheme</option>=<replaceable>COLOR_SCHEME</replaceable></arg>
      <arg><option>--git-notify=</option><replaceable>[auto|on|off]</replaceable></arg>
      <arg><option>--git-upstream-branch=</option><replaceable>TREEISH</replaceable></arg>
      <arg><option>--git-debian-branch=</option><replaceable>BRANCH_NAME</replaceable></arg>
      <arg><option>--git-ignore-branch</option></arg>
      <arg><option>--git-[no-]submodules</option></arg>
      <arg><option>--git-builder=</option><replaceable>BUILD_CMD</replaceable></arg>
      <arg><option>--git-cleaner=</option><replaceable>CLEAN_CMD</replaceable></arg>
      <arg><option>--git-[no-]pbuilder</option></arg>
      <arg><option>--git-[no-]qemubuilder</option></arg>
      <arg><option>--git-dist=</option><replaceable>DIST</replaceable></arg>
      <arg><option>--git-arch=</option><replaceable>ARCH</replaceable></arg>
      <arg><option>--git-[no-]pbuilder-autoconf</option></arg>
      <arg><option>--git-pbuilder-options</option>=<replaceable>PBUILDER_OPTIONS</replaceable></arg>
      <arg><option>--git-[no-]sign-tags</option></arg>
      <arg><option>--git-keyid=</option><replaceable>GPG-KEYID</replaceable></arg>
      <arg><option>--git-posttag=</option><replaceable>COMMAND</replaceable></arg>
      <arg><option>--git-postbuild=</option><replaceable>COMMAND</replaceable></arg>
      <arg><option>--git-postexport=</option><replaceable>COMMAND</replaceable></arg>
      <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-force-create</option></arg>
      <arg><option>--git-no-create-orig</option></arg>
      <arg><option>--git-upstream-tree=</option><replaceable>[TAG|BRANCH|TREEISH]</replaceable></arg>
      <arg><option>--git-tarball-dir=</option><replaceable>DIRECTORY</replaceable></arg>
      <arg><option>--git-compression=</option><replaceable>TYPE</replaceable></arg>
      <arg><option>--git-compression-level=</option><replaceable>LEVEL</replaceable></arg>
      <arg><option>--git-export-dir=</option><replaceable>DIRECTORY</replaceable></arg>
      <arg><option>--git-export=</option><replaceable>TREEISH</replaceable></arg>
      <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>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>
    <para>
    &gbp-buildpackage; is used to build &debian; source and .deb packages from
    a &git; repository.
    </para>
    <para>
    &gbp-buildpackage; will, in order:
    </para>
    <itemizedlist>
      <listitem>
        <para>
        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.
        </para>
      </listitem>
      <listitem>
        <para>
        Verify that it is being executed from the correct branch.
        </para>
      </listitem>
      <listitem>
        <para>
	  (Optionally) run a clean command specified
	  with <option>--git-cleaner</option>.
        </para>
      </listitem>
      <listitem>
        <para>
        (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;.
        </para>
      </listitem>
      <listitem>
        <para>
          (Optionally) call a pre build hook.
        </para>
      </listitem>
      <listitem>
        <para>
          Call <application>debuild</application>(1) or &cowbuilder;
          (via <option>--git-pbuilder</option>) or the application
          specified via <option>--git-builder</option> passing along
          all arguments given to &gbp-buildpackage; on the command
          line that don't start with --git-.
        </para>
      </listitem>
      <listitem>
        <para>
        (Optionally) tag the tree after a successful build.
        </para>
      </listitem>
      <listitem>
        <para>
        (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.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>
  <refsect1>
    <title>OPTIONS</title>
    <para>
      All options are prefixed with <option>git-</option> to
      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. 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> instead of
          <command>debuild clean</command>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-pbuilder</option>
        </term>
        <listitem>
          <para>
          Build package using <command>git-pbuilder</command>. 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
          <command>--git-pbuilder</command>. If unset build for the unstable
          distribution. The special value <option>DEP14</option> 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
          <command>--git-pbuilder</command>. 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 <command>git-pbuilder</command> or to
          rely on the settings in .pbuilderrc. See the
          <command>git-pbuilder</command> manpage for details.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-pbuilder-options</option>
        </term>
        <listitem>
          <para>
          Options to pass to pbuilder
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-verbose</option>
        </term>
        <listitem>
          <para>
          verbose execution
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-color=</option><replaceable>[auto|on|off]</replaceable>
        </term>
        <listitem>
          <para>
          Whether to use colored output.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-notify=</option><replaceable>[auto|on|off]</replaceable>
        </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
          '&lt;debug&gt;:&lt;info&gt;:&lt;warning&gt;:&lt;error&gt;'.
          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>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-upstream-tree=</option><replaceable>[TAG|BRANCH|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. 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[-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>
  </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.
    </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:
    </para>
    <screen>
      DIST=wheezy ARCH=i386 &git-pbuilder; create
    </screen>
  </refsect1>
  <refsect1>
    &man.gbp.config-files;
    <para>
      All options in the config files must be specified without the 'git-'
      prefix. So
      e.g. <option>--git-debian-branch</option>=<replaceable>debian/sid</replaceable>
      becomes in &gbp.conf;:
    </para>
    <programlisting>
      [buildpackage]
      debian-dir  = debian/sid
    </programlisting>
  </refsect1>
  <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>,
    <xref linkend="man.gbp.conf"/>,
    &man.seealso.common;
    </para>
  </refsect1>
  <refsect1>
    <title>AUTHOR</title>
    <para>
    &dhusername; &dhemail;
    </para>
  </refsect1>
</refentry>