buildpackage{,-rpm}: add preexport hook

Sometimes it is necessary to perform operations before preparing the
tarballs and exporting to the build directory.
One such case is when having to handle extremely large binary assets in
the orig tarball and at the same time complex packaging code, which
makes it desirable to separate the two into different repositories for
easier handling.
A pre-export hook allows to ensure that the tarball repository is
present and checked out at the correct branch.

Closes: #909266

Signed-off-by: Luca Boccassi <bluca@debian.org>

3 files changed, 46 insertions, 2 deletions

diff --git a/docs/chapters/building.xml b/docs/chapters/building.xml
index 1fbd5ae3..af1fe318 100644
--- a/docs/chapters/building.xml
+++ b/docs/chapters/building.xml
@@ -267,5 +267,17 @@ rm -f rules.* control.*
 exit 0
 </programlisting>
     </sect2>
+    <sect2 id="gbp.building.preexport">
+    <title>Running preexport hook</title>
+    <para>&gbp-buildpackage; exports several variables into the
+	<option>preexport</option>'s environment (for details see
+	the <xref linkend="man.gbp.buildpackage"/> manual page). The motivation
+	for the preexport action is to allow further actions before preparing and
+	exporting the orig tarballs to the build directory.
+	A usecase could be having the orig tarballs in a separate repository due to
+	very large binary assets, that need to be checked out to the correct branch
+	before creating the tarballs.
+    </para>
+    </sect2>
     </sect1>
 </chapter>
diff --git a/docs/manpages/gbp-buildpackage-rpm.xml b/docs/manpages/gbp-buildpackage-rpm.xml
index 9f8f4381..18a0a1e1 100644
--- a/docs/manpages/gbp-buildpackage-rpm.xml
+++ b/docs/manpages/gbp-buildpackage-rpm.xml
@@ -39,6 +39,7 @@
       <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-preexport=</option><replaceable>COMMAND</replaceable></arg>
       <arg><option>--git-[no-]build</option></arg>
       <arg><option>--git-[no-]hooks</option></arg>
       <arg><option>--git-packaging-tag=</option><replaceable>TAG-FORMAT</replaceable></arg>
@@ -336,6 +337,21 @@
         </listitem>
       </varlistentry>
       <varlistentry>
+        <term><option>--git-preexport=</option><replaceable>COMMAND</replaceable>
+        </term>
+        <listitem>
+          <para>
+          Execute <replaceable>COMMAND</replaceable> before exporting the source
+          tree.
+          </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-postexport=</option><replaceable>COMMAND</replaceable>
         </term>
         <listitem>
@@ -382,7 +398,7 @@
         </term>
         <listitem>
           <para>
-          Enable running all (cleaner, postexport, prebuild, postbuild, and
+          Enable running all (cleaner, preexport, postexport, prebuild, postbuild, and
           posttag) hooks. Note: the <option>--git-builder</option> command is
           not affected by this option.
           </para>
diff --git a/docs/manpages/gbp-buildpackage.xml b/docs/manpages/gbp-buildpackage.xml
index 9b6bcce3..d25f5c89 100644
--- a/docs/manpages/gbp-buildpackage.xml
+++ b/docs/manpages/gbp-buildpackage.xml
@@ -39,6 +39,7 @@
       <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-preexport=</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-postbuild=</option><replaceable>COMMAND</replaceable></arg>
@@ -460,6 +461,21 @@
       </para>
       <variablelist>
 	<varlistentry>
+          <term><option>--git-preexport=</option><replaceable>COMMAND</replaceable>
+          </term>
+          <listitem>
+            <para>
+              Execute <replaceable>COMMAND</replaceable> before 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_BUILD_DIR</envar> (the build dir).
+            </para>
+          </listitem>
+	</varlistentry>
+	<varlistentry>
           <term><option>--git-postexport=</option><replaceable>COMMAND</replaceable>
           </term>
           <listitem>
@@ -531,7 +547,7 @@
           </term>
           <listitem>
             <para>
-              Enable running all (cleaner, postexport, prebuild, postbuild, and
+              Enable running all (cleaner, preexport, postexport, prebuild, postbuild, and
               posttag) hooks. Note: the <option>--git-builder</option> command is
               not affected by this option.
             </para>