New command to merge in changes from a upstream using git

This reverts commit 3384a0f7a763144e5d627c454d7d76c2841e553b.

6 files changed, 261 insertions, 0 deletions

diff --git a/docs/Makefile b/docs/Makefile
index b7258a47..d1567e5e 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -11,6 +11,7 @@ MAN1S = \
         gbp-import-dsc    \
         gbp-import-dscs   \
         gbp-import-orig   \
+        gbp-import-ref    \
         gbp-pq            \
         gbp-pristine-tar  \
         gbp-pull          \
diff --git a/docs/common.ent b/docs/common.ent
index 7f180064..d15440fd 100644
--- a/docs/common.ent
+++ b/docs/common.ent
@@ -25,6 +25,7 @@
   <!ENTITY gbp-import-dsc	"<command>gbp&nbsp;import-dsc</command>">
   <!ENTITY gbp-import-dscs	"<command>gbp&nbsp;import-dscs</command>">
   <!ENTITY gbp-import-orig	"<command>gbp&nbsp;import-orig</command>">
+  <!ENTITY gbp-import-ref	"<command>gbp&nbsp;import-ref</command>">
   <!ENTITY gbp-import-srpm      "<command>gbp&nbsp;import-srpm</command>">
   <!ENTITY gbp-pq		"<command>gbp&nbsp;pq</command>">
   <!ENTITY gbp-pq-export	"<command>gbp&nbsp;pq&nbsp;<option>export</option></command>">
diff --git a/docs/man.gbp.xml b/docs/man.gbp.xml
index f77a1333..8d044a81 100644
--- a/docs/man.gbp.xml
+++ b/docs/man.gbp.xml
@@ -22,6 +22,7 @@
 &man.gbp.importdsc;
 &man.gbp.importdscs;
 &man.gbp.importorig;
+&man.gbp.importref;
 &man.gbp.import.srpm;
 &man.gbp.pq;
 &man.gbp.pq.rpm;
diff --git a/docs/manpages/gbp-import-ref.xml b/docs/manpages/gbp-import-ref.xml
new file mode 100644
index 00000000..77f7447f
--- /dev/null
+++ b/docs/manpages/gbp-import-ref.xml
@@ -0,0 +1,256 @@
+<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 specifiy 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> (the default) merges from the upstream branch.
+            <replaceable>VERSION</replaceable> 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 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
+-->
diff --git a/docs/manpages/manpages.ent b/docs/manpages/manpages.ent
index 452f83a5..b53ff4e4 100644
--- a/docs/manpages/manpages.ent
+++ b/docs/manpages/manpages.ent
@@ -12,6 +12,7 @@
 <!ENTITY man.gbp.importdsc SYSTEM "gbp-import-dsc.xml">
 <!ENTITY man.gbp.importdscs SYSTEM "gbp-import-dscs.xml">
 <!ENTITY man.gbp.importorig SYSTEM "gbp-import-orig.xml">
+<!ENTITY man.gbp.importref SYSTEM "gbp-import-ref.xml">
 <!ENTITY man.gbp.pq SYSTEM "gbp-pq.xml">
 <!ENTITY man.gbp.pq.rpm SYSTEM "gbp-pq-rpm.xml">
 <!ENTITY man.gbp.pristine.tar SYSTEM "gbp-pristine-tar.xml">
diff --git a/docs/manual.xml b/docs/manual.xml
index 35a4e417..09a7a1fb 100644
--- a/docs/manual.xml
+++ b/docs/manual.xml
@@ -39,6 +39,7 @@
     &man.gbp.importdsc;
     &man.gbp.importdscs;
     &man.gbp.importorig;
+    &man.gbp.importref;
     &man.gbp.pq;
     &man.gbp.pristine.tar;
     &man.gbp.pull;