<refentry id="man.gbp.import.ref">
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
  </refentryinfo>
  <refmeta>
    <refentrytitle>gbp-import-ref</refentrytitle>
    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>gbp-import-ref</refname>
    <refpurpose>Update upstream sources when using &git; only</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      &gbp-import-ref;

      &man.common.options.synopsis;
      <arg><option>--upstream-version=</option><replaceable>version</replaceable></arg>
      <arg><option>--merge-mode=</option><replaceable>[auto|merge|replace]</replaceable></arg>
      <arg><option>--upstream-branch=</option><replaceable>branch_name</replaceable></arg>
      <arg><option>--upstream-tag=</option><replaceable>tag_format</replaceable></arg>
      <arg><option>--upstream-tree=</option><replaceable>[BRANCH|VERSION|commit-id]</replaceable></arg>
      <arg><option>--debian-branch=</option><replaceable>branch_name</replaceable></arg>
      <arg><option>--[no-]sign-tags</option></arg>
      <arg><option>--keyid=</option><replaceable>gpg-keyid</replaceable></arg>
      <arg><option>--postimport=cmd</option></arg>
      <arg><option>--[no-]rollback</option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>
    <para>
      &gbp-import-ref; merges upstream git commits onto your &debian-branch;
      You can either specify a branch to merge, give an upstream
      version or specify the commit id directly. If no tag exists for the imported
      commit it will be automatically created.
    </para>
  </refsect1>
  <refsect1>
    <title>OPTIONS</title>
    <variablelist>
      &man.common.options.description;

      <varlistentry>
        <term><option>--upstream-version</option>=<replaceable>version</replaceable></term>
        <term><option>-u</option><replaceable>version</replaceable></term>
        <listitem>
          <para>
            The upstream version to merge. The upstream tag to use will be determined via
	    the <option>--upstream-tag</option>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--merge-mode=</option><replaceable>[auto|merge|replace]</replaceable></term>
        <listitem>
          <para>
            How to fold the upstream commits onto the
            &debian; packaging branch.
	  </para>
	  <para>
	    <replaceable>merge</replaceable> does a
	    &git; <command>merge</command> leaving you on your own in
	    case of merge conflict resolution.
	  </para>
	  <para>
	    <replaceable>replace</replaceable> mode on the
	    other hand makes the head of the &debian; packaging branch
	    identical to the newly imported tree but preserves the
	    content of the <filename>debian/</filename> directory
	    while keeping the current head as well as the newly
	    imported tree as parents of the generated commit. This is
	    similar to a <option>theirs</option> merge strategy while
	    preserving <filename>debian/</filename>.
          </para>
	  <para>
	    The default is <replaceable>auto</replaceable> which
	    uses <replaceable>replace</replaceable> for 3.0 (quilt) packages
	    and <replaceable>merge</replaceable> otherwise.
	  </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--upstream-branch</option>=<replaceable>branch_name</replaceable>
        </term>
        <listitem>
          <para>
            The branch in the &git; repository the upstream sources are
            on.  Default is <replaceable>upstream</replaceable>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--upstream-tag=</option><replaceable>tag-format</replaceable>
        </term>
        <listitem>
          <para>
            Use this tag format when looking up upstream tags,
            default is <replaceable>upstream/%(version)s</replaceable>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--upstream-tree=</option><replaceable>[BRANCH|VERSION|commit-id]</replaceable>
        </term>
        <listitem>
          <para>
	    What to merge into the &debian-branch;.
            <replaceable>BRANCH</replaceable> merges from the upstream branch.
            <replaceable>VERSION</replaceable> (the default) looks for a tag determined from the given
	    upstream version number via the <option>--upstream-version</option> option.
	  </para>
	  <para>
	    Other values are interpreted as git commit id to merge from.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--debian-branch</option>=<replaceable>branch_name</replaceable>
        </term>
        <listitem>
          <para>
            The branch in the &git; repository the &debian; package is being
            developed on, default is <replaceable>master</replaceable>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--[no-]sign-tags</option>
        </term>
        <listitem>
          <para>
            GPG sign all created tags.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--keyid=</option><replaceable>gpg-keyid</replaceable>
        </term>
        <listitem>
          <para>
            Use this <option><replaceable>keyid</replaceable></option>
            for gpg signing tags.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--import-msg=</option><replaceable>msg-format</replaceable>
        </term>
        <listitem>
          <para>
            Use this format string for the commit message when importing upstream
            versions, default is
            <replaceable>New upstream version %(version)s</replaceable>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--postimport=<replaceable>cmd</replaceable></option></term>
        <listitem>
          <para>
            Run <replaceable>cmd</replaceable> after the import. The
            hook gets the following environment variables passed:
	    <variablelist>
	      <varlistentry>
		<term><envar>GBP_BRANCH</envar></term>
		<listitem><para>
		  The name of the Debian packaging branch
		</para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term><envar>GBP_TAG</envar></term>
		<listitem><para>
		  The name of the just created upstream tag
		</para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term><envar>GBP_UPSTREAM_VERSION</envar></term>
		<listitem><para>
		  The just imported upstream version
		</para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term><envar>GBP_DEBIAN_VERSION</envar></term>
		<listitem><para>
		  The Debian version of the package with a Debian
		  revision of '-1'
		</para></listitem>
	      </varlistentry>
	    </variablelist>
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--[no-]rollback</option></term>
        <listitem>
          <para>
	    Rollback changes in case of an error.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>EXAMPLES</title>
    <para>
      Merge commits from the &upstream-branch; into the &debian-branch;
      creating a tag for the version <replaceable>0.0~git20180524</replaceable>:
    </para>
    <screen>
    &gbp-import-ref; --upstream-tree=BRANCH -u0.0~git20180524</screen>
    <para>
      Merge commits from the tag corresponding to version <replaceable>1.0</replaceable>:
    </para>
    <screen>
    &gbp-import-ref; --upstream-tree=VERSION -u1.0</screen>
    <para>
      Merge commits given by a SHA1 creating a tag for the version
      <replaceable>0.0~git20180524</replaceable>
    </para>
    <screen>
    &gbp-import-ref; --upstream-tree=c4398912c -u0.0~git20180524</screen>
  </refsect1>
  <refsect1>
    &man.gbp.config-files;
  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <xref linkend="man.gbp.buildpackage"/>,
      <xref linkend="man.gbp.import.dsc"/>,
      <xref linkend="man.gbp.import.dscs"/>,
      <xref linkend="man.gbp.dch"/>,
      <xref linkend="man.gbp.conf"/>,
      <citerefentry>
        <refentrytitle>uscan</refentrytitle>
        <manvolnum>1</manvolnum>
	</citerefentry>,
	&man.seealso.common;
    </para>
  </refsect1>
  <refsect1>
    <title>AUTHOR</title>
    <para>
      &dhusername; &dhemail;
    </para>
  </refsect1>
</refentry>
<!--  LocalWords:  xz lzma bzip gzip tarball
-->
