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

<refentry id="man.gbp.pq">
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
  </refentryinfo>
  <refmeta>
   <refentrytitle>gbp-pq</refentrytitle>
    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>gbp-pq</refname>
    <refpurpose>Manage quilt patches on patch queue branches in git</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      &gbp-pq;
      &man.common.options.synopsis;
      <arg><option>--[no-]patch-numbers</option></arg>
      <arg><option>--patch-num-format=</option><replaceable>format</replaceable></arg>
      <arg><option>--[no-]renumber</option></arg>
      <arg><option>--topic=</option><replaceable>topic</replaceable></arg>
      <arg><option>--time-machine=</option><replaceable>num</replaceable></arg>
      <arg><option>--[no-]drop</option></arg>
      <arg><option>--force</option></arg>
      <arg><option>--meta-closes=bug-close-tags</option></arg>
      <arg><option>--meta-closes-bugnum=bug-number-format</option></arg>
      <group choice="plain">
        <arg><option>drop</option></arg>
        <arg><option>export</option></arg>
        <arg><option>import</option></arg>
        <arg><option>rebase</option></arg>
        <arg><option>switch</option></arg>
      </group>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>
    <para>
    &gbp-pq; helps one to manage quilt patches in &debian; packages that are
    maintained with &gbp;. This is especially useful with packages using the
    3.0 (quilt) source format. With &gbp-pq;, you can maintain the quilt patches
    that should be applied to a package on a separate branch called patch-queue
    branch. So if your &debian; package lives on
    <replaceable>master</replaceable>, the associated patch-queue branch will be
    called <replaceable>patch-queue/master</replaceable>.
    </para>
    <para>
    See <ulink url="https://honk.sigxcpu.org/piki/development/debian_packages_in_git/"></ulink>
    for example workflows.
    </para>
  </refsect1>
  <refsect1>
    <title>ACTIONS</title>
    <variablelist>
      <varlistentry>
        <term><option>import</option>
        </term>
        <listitem>
          <para>
          Create a patch queue branch from quilt patches in debian/patches/
          that are listed in debian/patches/series. The patches must apply
          without fuzz.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>export</option>
        </term>
        <listitem>
          <para>
          Export the patches on the patch-queue branch associated to the
          current branch into a quilt patch series in debian/patches/ and
          update the series file.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>rebase</option>
        </term>
        <listitem>
          <para>
          Switch to the patch-queue branch associated to the current branch and
          rebase it against the current branch.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>drop</option>
        </term>
        <listitem>
          <para>
          Drop (delete) the patch queue associated to the current branch. So if
          you're on branch <replaceable>foo</replaceable>, this would drop
          branch <replaceable>patch-queue/foo</replaceable>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>apply</option>
        </term>
        <listitem>
          <para>
          Add a single patch to the patch-queue similar to using
          <command>git-am</command>. Use <option>--topic</option> if you want
          the patch to appear in a separate subdir when exporting the patch queue
          using <option>export</option>. This can be used to separate upstream
          patches from &debian; specific patches.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>switch</option>
        </term>
        <listitem>
          <para>
          Switch to the patch-queue branch if on the base branch and switch
          to base branch if on patch-queue branch.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>OPTIONS</title>
    <variablelist>
      &man.common.options.description;

      <varlistentry>
        <term><option>--[no-]patch-numbers</option>
        </term>
        <listitem>
          <para>
          Whether or not the patch files should be prefixed with a number.
          The default is to export patches with patch numbers. Note,
          however, that this normally affects patches whose names are
          automatically generated, and has no effect on exporting patches
          which have a <option>Gbp[-Pq]: Name</option> tag, since the
          name specified is preserved unless the <option>--renumber</option>
          option is used.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--patch-num-format=</option><replaceable>format</replaceable>
        </term>
        <listitem>
          <para>
          The format specifier for patch number prefixes. The default format is '%04d-'.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--[no-]renumber</option>
        </term>
        <listitem>
          <para>
          Whether or not to renumber patches exported from the patch queue,
          instead of preserving numbers specified in
          <option>Gbp-Pq: Name</option> tags. The default is not to renumber
          patches. Useful when patches need to be renamed for the sake of
          uniformity. For example, using <option>--renumber</option> with
          <option>--no-patch-num</option> will strip all numeric prefixes from
          exported patches.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--topic=</option><replaceable>topic</replaceable>
        </term>
        <listitem>
          <para>
          Topic to use when importing a single patch
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--time-machine=</option><replaceable>NUM</replaceable>
        </term>
        <listitem>
          <para>
          When importing a patch queue fails, go back commit-by-commit on the
          current branch to check if the patch-queue applies there. Do this at
          most <replaceable>NUM</replaceable> times. This can be useful if the
          patch-queue doesn't apply to the current branch HEAD anymore, e.g.
          after importing a new upstream version.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--[no-]drop</option></term>
        <listitem>
          <para>Whether to drop (delete) the patch queue branch after
          a successful export</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--force</option></term>
        <listitem>
          <para>In case of <option>import</option>, import even if the branch already
            exists</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--meta-closes=</option><replaceable>bug-close-tags</replaceable>
        </term>
        <listitem>
          <para>
          What meta tags to look for to generate a commit message when
          using <option>export</option> <option>--commit</option>.
          The default is <literal>'Closes|LP'</literal> to support Debian and Launchpad.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--meta-closes-bugnum=</option><replaceable>bug-number-format</replaceable>
        </term>
        <listitem>
          <para>
            What regular expression should be used to parse out the
            bug number when using
	    <option>export</option> <option>--commit</option>.  The
            default is <literal>'(?:bug|issue)?\#?\s?\d+'</literal>.
            See <xref linkend="man.gbp.dch"/> for details.
          </para>
        </listitem>
      </varlistentry>
     </variablelist>
  </refsect1>
  <refsect1>
    <title>TAGS</title>
    <para>
    When exporting patches from a patch-queue branch, &gbp-pq; will look at the
    patch header for special tags it recognizes. All tags need to start at the
    first column and require at least one whitespace after the colon.
    </para>
    <variablelist>
      <varlistentry>
        <term><option>Gbp[-Pq]: Ignore</option>
        </term>
        <listitem>
          <para>
          Ignores the commit, no patch is generated out of it.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>Gbp[-Pq]: Name</option> <replaceable>name</replaceable>
        </term>
        <listitem>
          <para>
	    The name to use for the patch when running
	    <screen>&gbp-pq; export</screen>
	    If unset, it will be formatted like
	    <command>git am</command> would format it.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>Gbp[-Pq]: Topic</option> <replaceable>topic</replaceable>
        </term>
        <listitem>
          <para>
          Moves the patch into a subdir called <replaceable>topic</replaceable>
          when running <screen>&gbp-pq; export</screen> This allows for some
          structure below <filename>debian/patches</filename>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>Gbp-Pq-Topic:</option> <replaceable>topic</replaceable>
        </term>
        <listitem>
          <para>
          Deprecated: use <option>Gbp[-Pq]: Topic</option>
          <replaceable>topic</replaceable> instead.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <xref linkend="man.gbp.buildpackage"/>,
      <citerefentry>
        <refentrytitle>dpkg-source</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>quilt</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>,
      <xref linkend="man.gbp.conf"/>
    </para>
  </refsect1>
  <refsect1>
    <title>AUTHOR</title>
    <para>
      &dhusername; &dhemail;
    </para>
  </refsect1>
</refentry>