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

<refentry id="man.gbp.import.orig">
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
  </refentryinfo>
  <refmeta>
    <refentrytitle>gbp-import-orig</refentrytitle>
    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>gbp-import-orig</refname>
    <refpurpose>Import an upstream source into a git repository</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      &gbp-import-orig;

      &man.common.options.synopsis;
      <arg><option>--upstream-version=</option><replaceable>version</replaceable></arg>
      <arg><option>--[no-]merge</option></arg>
      <arg><option>--merge-mode=</option><replaceable>[merge|replace]</replaceable></arg>
      <arg><option>--upstream-branch=</option><replaceable>branch_name</replaceable></arg>
      <arg><option>--debian-branch=</option><replaceable>branch_name</replaceable></arg>
      <arg><option>--upstream-vcs-tag=</option><replaceable>tag-format</replaceable></arg>
      <arg><option>--[no-]sign-tags</option></arg>
      <arg><option>--keyid=</option><replaceable>gpg-keyid</replaceable></arg>
      <arg><option>--upstream-tag=</option><replaceable>tag-format</replaceable></arg>
      <arg><option>--filter=</option><replaceable>pattern</replaceable></arg>
      <arg><option>--[no-]pristine-tar</option></arg>
      <arg><option>--[no-]filter-pristine-tar</option></arg>
      <arg><option>--[no-]symlink-orig</option></arg>
      <arg><option>--postimport=cmd</option></arg>
      <arg><option>--[no-]interactive</option></arg>
      <arg><option>--download</option></arg>
      <group choice="plain">
        <arg choice="plain"><replaceable>upstream-source</replaceable></arg>
        <arg><option>--uscan</option></arg>
      </group>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>
    <para>
    &gbp-import-orig; imports <replaceable>upstream-source</replaceable> into
    the &git; repository. <replaceable>upstream-source</replaceable> can either
    be a gzip, bzip2, lzma or xz compressed tar archive, a zip archive, or an
    already unpacked source tree. If it is already of the form
    <replaceable>package-name_version.orig.tar.gz</replaceable>, the version
    information is read from the tarball's filename, otherwise it can be given
    on the command line via <option>--upstream-version</option>.  If the source
    package name or version can't be determined, &gbp-import-orig; will prompt
    for it unless <option>--no-interactive</option> is given.
    </para>
    <para>
    The sources are placed on the upstream branch (default:
    <replaceable>upstream</replaceable>), tagged and merged onto the debian
    branch (default: <replaceable>master</replaceable>).
    </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 number
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--[no-]merge</option></term>
        <listitem>
          <para>
          Merge the upstream branch to the &debian; branch after import
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--merge-mode=</option><replaceable>[merge|replace]</replaceable></term>
        <listitem>
          <para>
            How to fold the newly imported upstream source to the
            &debian; packaging branch after import.
	  </para>
	  <para>
	    The default mode
	    <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
	    important trees as parents of the generated commit. This is
	    similar to a <option>theirs</option> merge strategy while
	    preserving <filename>debian/</filename>.
          </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 put
          onto. Default is <replaceable>upstream</replaceable>.
          </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>. After
          importing the new sources on the upstream branch, &gbp-import-orig;
          will try to merge the new version onto this branch.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--upstream-vcs-tag</option>=<replaceable>tag-format</replaceable>
        </term>
        <listitem>
          <para>
          Add <replaceable>tag-format</replaceable> as additional parent to the
          commit of the upstream tarball. Useful when upstream uses git and you
          want to link to its revision history. The
          <replaceable>tag-format</replaceable> can be a pattern similar to
          what <option>--upstream-tag</option> supports.
          </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 keyid for gpg signing tags
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--upstream-tag=</option><replaceable>tag-format</replaceable>
        </term>
        <listitem>
          <para>
          use this tag format when tagging upstream versions,
          default is <replaceable>upstream/%(version)s</replaceable>
          </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>Imported Upstream version %(version)s</replaceable>
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--filter=</option><replaceable>pattern</replaceable>
        </term>
        <listitem>
          <para>
          filter out files glob-matching pattern. Can be given multiple times.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--[no-]pristine-tar</option>
        </term>
        <listitem>
          <para>
          generate <command>pristine-tar</command> delta file
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--[no-]filter-pristine-tar</option>
        </term>
        <listitem>
          <para>
          if using a filter, also filter the files out of the tarball
          passed to <command>pristine-tar</command>
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--[no-]symlink-orig</option></term>
        <listitem>
          <para>
          Whether to create and keep a symlink from the upstream tarball
          to a &debian; policy conformant upstream tarball name located in
          <filename class="directory">../</filename>.
          </para>
          <para>
          This is a good idea if not using <command>pristine-tar</command>
          since it avoids creating a new tarball with a different md5sum.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--postimport=<replaceable>cmd</replaceable></option></term>
        <listitem>
          <para>
          run <replaceable>cmd</replaceable> after the import.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--uscan</option></term>
        <listitem>
          <para>
          Use uscan to fetch new upstream version.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--uscan</option></term>
        <listitem>
          <para>
            Download the tarball from the given HTTP URL. This needs
            python-request installed.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--[no-]interactive</option></term>
        <listitem>
          <para>
          Run command interactively, i.e. ask package name and version if
          needed.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>EXAMPLES</title>
    <para>
    Download and import a new upstream version using the information from <filename>debian/watch</filename>
    </para>
    <screen>
      &gbp-import-orig; --uscan
    </screen>
    <para>
    After downloading an upstream tarball by hand, import it
    </para>
    <screen>
      &gbp-import-orig; ../upstream-tarball-0.1.tar.gz
    </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"/>,
      &man.seealso.common;
    </para>
  </refsect1>
  <refsect1>
    <title>AUTHOR</title>
    <para>
    &dhusername; &dhemail;
    </para>
  </refsect1>
</refentry>
<!--  LocalWords:  xz lzma bzip gzip tarball
 -->