<para>
The &git-buildpackage-rpm; tool is used for building.
The tool creates the source tarball and copies it and the packaging files
- to a separate build directory and builds the package there. By default,
- &rpmbuild; is used as the builder command. You can define a different builder
- command with the <option>--git-builder</option> option.
+ to a separate build directory and builds the package there. By default,
+ &rpmbuild; is used as the builder command. You can define a different
+ builder command with the <option>--git-builder</option> option.
</para>
+
+ <para>
+ To build the (non-native) package when on <emphasis>packaging-branch</>,
+ using pristine-tar to create upstream tarball:
+ <screen>
+ $ &git-buildpackage-rpm; --pristine-tar
+ </screen>
+ During development, if you have unclean git tree (untracked files and/or
+ uncommitted changes) you may use:
+ <screen>
+ $ &git-buildpackage-rpm; --git-ignore-untracked
+ </screen>
+ or:
+ <screen>
+ $ &git-buildpackage-rpm; --git-ignore-new
+ </screen>
+ </para>
+
+ <para>
+ Git-buildpackage-rpm always builds in a separate build directory
+ (<emphasis>./rpmbuild/</emphasis> by default). You may change that and also
+ build a different revision that your current branch HEAD. The revision can
+ be any git "commit-ish", i.e. branch or tag name or a commit sha1.
+ Git-buildpackage also supports some "special revisions", i.e.
+ <emphasis>INDEX</> refer to the current index,
+ <emphasis>WC</> or <emphasis>WC.IGNORED</> refer to the current working
+ copy with all (even untracked and ignored) files,
+ <emphasis>WC.TRACKED</> refers to the current working copy of the files
+ tracked by git,
+ <emphasis>WC.UNTRACKED</> refers to the current working copy of all files
+ excluding ignore files.
+ Some examples:
+ <screen>
+ $ &git-buildpackage-rpm; --git-export-dir=/home/user/rpmbuild
+ $ &git-buildpackage-rpm; --git-export-dir=/home/user/rpmbuild --git-export=v1.2.3
+ $ &git-buildpackage-rpm; --git-export=WC.UNTRACKED
+ $ &git-buildpackage-rpm; --git-export=INDEX
+ $ &git-buildpackage-rpm; --git-export=feature/cool-new-thing
+ $ &git-buildpackage-rpm; --git-export=8d55173610f
+ </screen>
+ </para>
+
+ <sect1 id="gbp.rpm.building.patch-generation">
+ <title>Automatic patch generation</title>
+ <para>
+ When developing a non-native package with packaging and sources
+ in the same branch
+ (see <xref linkend="gbp.rpm.development.models.nonnative1">)
+ you usually want for git-buildpackage-rpm to automatically generate
+ patches. In this mode, git-buildpackage-rpm generates the upstream
+ tarball and copies packaging files to the build dir. After that it
+ generates patches from commits between <option>upstream</> and the
+ revision to be built, and, updates the spec file accordingly.
+ Git-buildpackage-rpm also have some options to alter the patch
+ generation. Build package with patch generation:
+ <screen>
+ $ &git-buildpackage-rpm; --git-patch-export
+ </screen>
+ Ignore changes to packaging/ directory and compress patches larger
+ than 100 kilobytes:
+ <screen>
+ $ &git-buildpackage-rpm; --git-patch-export --git-patch-export-compress=100k --git-patch-export-ignore-path='^packaging/.*'
+ </screen>
+ </para>
+ </sect1>
+
+ <sect1 id="gbp.rpm.building.patch-queue">
+ <title>Working with separate development branch</title>
+ <para>
+ When developing a non-native package with packaging data and source
+ code in separate branches
+ (see <xref linkend="gbp.rpm.development.models.nonnative2">)
+ you use the &gbp-pq-rpm; tool to handle the patches. You work on the
+ source code on the development branch and then <emphasis>export</>
+ the patches to the packaging branch when building the RPM package.
+ </para>
+
+ <para>
+ Create a <emphasis>development</> (or <emphasis>patch-queue</>) branch
+ by applying the patches in current packaging branch on top of the
+ upstream version. This will create a new branch, e.g.
+ <emphasis>development/master</> assuming your current branch is
+ <emphasis>master</>. Simply:
+ <screen>
+ $ &gbp-pq-rpm; import
+ </screen>
+ Now you can develop normally on the development branch (add, remove,
+ rebase, amend commits). Just make sure you stay based on the correct
+ upstream version, if doing git-rebase. After you're happy with your
+ changes and you're ready to build an RPM package, you have to
+ <emphasis>export</> the patches with &gbp-pq-rpm;. This will change
+ back to you packaging branch, generate patches from commits between
+ between <emphasis>upstream</> and the HEAD of the development branch
+ and update the spec file with the new patches:
+ <screen>
+ $ &gbp-pq-rpm; export
+ </screen>
+ Commit the changes to packaging branch, and build. For example:
+ <screen>
+ $ <command>git add</> *patch *spec
+ $ <command>git commit</> -a
+ $ &git-buildpackage-rpm
+ </screen>
+ Of course you can build even without committing by using the
+ <option>--git-export=WC.UNTRACKED</> option of &git-buildpackage-rpm;.
+ </para>
+
+ <para>
+ Moving to a new upstream version is basically simple. Assuming you
+ have imported/pulled new upstream version to your git-tree, just:
+ <screen>
+ $ <command>git checkout</> master
+ # Edit the spec file and change the 'Version:' tag to new upstream version
+ $ <command>vim</> *spec
+ $ <command>git commit</> *spec
+ $ &gbp-pq-rpm; rebase
+ </screen>
+ However, if the patches do not apply cleanly, you have to manually
+ apply and resolve the patches.
+ </para>
+ </sect1>
+
</chapter>
<!ENTITY ch.intro-rpm SYSTEM "intro-rpm.sgml">
-<!ENTITY ch.setup-rpm SYSTEM "setup-rpm.sgml">
+<!ENTITY ch.development-rpm SYSTEM "development-rpm.sgml">
<!ENTITY ch.building-rpm SYSTEM "building-rpm.sgml">
--- /dev/null
+<chapter id="gbp.rpm.development">
+ <title>Development flow</title>
+
+ <sect1 id="gbp.rpm.development.models">
+ <title>Development models</title>
+ <para>
+ The &git-buildpackage-rpm; toolset basically supports three different
+ models of package maintenance.
+ </para>
+
+ <sect2 id="gbp.rpm.development.models.native"
+ xreflabel="Native package">
+ <title>Native package</title>
+ <para>
+ This means that you are the upstream, there is no separate
+ upstream with which you have to sync. Basically, only
+ <option>packaging-branch</> is used - it contains both the source
+ code and packaging files. No patches should be present as all
+ changes can be directly committed to upstream (which is you).
+ When building, &git-buildpackage-rpm; will create the source
+ tarball and copy it and the packaging to the build directory.
+ </para>
+ </sect2>
+
+ <sect2 id="gbp.rpm.development.models.nonnative1"
+ xreflabel="Non-native package, model 1">
+ <title>Upstream package, alternative 1: packaging and sources in
+ the same branch</title>
+ <para>
+ This represents somewhat Debian-style package maintenance.
+ All changes (packaging and source code) are done to the same
+ branch, i.e., the <option>packaging-branch</>, based on the
+ <option>upstream-branch</>. When package is built,
+ &git-buildpackage-rpm; can automatically generate patches from
+ upstream version to packaging branch head (one patch per commit).
+ and modify the spec file accordingly.
+ </para>
+ </sect2>
+
+ <sect2 id="gbp.rpm.development.models.nonnative2"
+ xreflabel="Non-native package, model 2">
+ <title>Upstream package, alternative 2: packaging and sources in
+ separate branches</title>
+ <para>
+ In this model packaging files (spec and patches) are held in
+ <option>packaging-branch</> and upstream sources in
+ <option>upstream-branch</>.
+ Your code development is done on the <option>patch-queue-branch</>,
+ based on the <option>upstream-branch</>, which only contains source
+ code but no packaging files. When building the package,
+ &gbp-pq-rpm; tool is used to export patches from the patch queue
+ branch to the packaging branch and edit the spec file accordingly.
+ Finally, &git-buildpackage-rpm; will create the upstream source
+ tarball and export it and the packaging files to the build
+ directory, and, build the RPM package.
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="gbp.rpm.development.scratch">
+ <title>Starting from scratch with a non-native package</title>
+ <para>
+ In this case, you most probably want to package software not yet
+ found in your distro. First, create an empty repository:
+ <screen>
+ $ <command>mkdir</> mypackage
+ $ <command>cd</> mypackage
+ $ <command>git init</>
+ </screen>
+ Then, import the upstream sources, create the packaging/development
+ branch and add the rpm packaging files. You have two choices:
+ </para>
+
+ <orderedlist>
+ <listitem><para>
+ packaging files and development sources in the same branch
+ <screen>
+ $ <command>git-import-orig-rpm</> ../mypackage.tar.gz
+ # Optionally (recommended): add gbp.conf
+ $ <command>vim</> .gbp.conf && <command>git add</> .gbp.conf && <command>git commit</> -m"Add gbp.conf"
+ # Add packaging files to source tree under subdir 'packaging'
+ $ <command>mkdir</> packaging && <command>cd</> packaging
+ $ <command>vim</> mypackage.spec
+ $ <command>git add</> .
+ $ <command>git commit</> -m"Add packaging files"
+ </screen></para>
+ </listitem>
+
+ <listitem><para>
+ development sources and packaging files in separate branches
+ <screen>
+ $ <command>git-import-orig-rpm</> --no-merge ../mypackage.tar.gz
+ # Optionally (recommended): add gbp.conf
+ $ <command>vim</> .gbp.conf && <command>git add</> .gbp.conf && <command>git commit</> -m"Add gbp.conf"
+ # Add packaging files (to root of master branch)
+ $ <command>vim</> mypackage.spec
+ $ <command>git add </> .
+ $ <command>git commit</> -m"Add packaging files"
+ </screen></para>
+ </listitem>
+ </orderedlist>
+ </sect1>
+
+ <sect1 id="gbp.rpm.development.convert">
+ <title>Converting an existing git repository of a non-native package</>
+ <para>
+ In this case, you already have a git repository containing the
+ upstream source, but it was created neither with &gbp-clone; nor
+ &git-import-srpm;.
+ You need to have a separate branch for upstream sources.
+ If you already have that, you can simply rename that branch to the
+ default upstream-branch:
+ <screen>
+ $ <command>git branch</> -m my-old-upstream-branch upstream
+ </screen>
+ OR just add the name of your upstream branch to gbp.conf.
+ Then, you just create a packaging/development branch(es) with git and
+ add packaging files to the packaging branch. If you want to maintain
+ sources and packaging in the same branch
+ (<xref linkend="gbp.rpm.development.models.nonnative1">)
+ do something like:
+ <screen>
+ $ <command>git checkout</> -b master upstream
+ # Optionally (recommended): add gbp.conf
+ $ <command>vim</> .gbp.conf && <command>git add</> .gbp.conf && <command>git commit</> -m"Add gbp.conf"
+ # Add packaging files to source tree, add and commit the packaging files
+ # ...
+ </screen>
+ If you want to maintain development sources and packaging in separate
+ branches
+ (<xref linkend="gbp.rpm.development.models.nonnative2">):
+ <screen>
+ $ <command>git checkout</> --orphan master
+ $ <command>rm</> .git/index
+ $ <command>git commit</> --allow-empty -m"Create packaging branch"
+ # Optionally (recommended): add gbp.conf
+ $ <command>vim</> .gbp.conf && <command>git add</> .gbp.conf && <command>git commit</> -m"Add gbp.conf"
+ # Next, add and commit the packaging files (.spec etc)
+ $ <command>vim</> mypackage.spec && <command>git add</> mypackage.spec && <command>git commit</> -m"Add packaging files"
+ # Now, you can create the development branch (and import possible patches)
+ $ &gbp-pq-rpm; import
+ </screen>
+ </para>
+ </sect1>
+</chapter>
+
<chapter id="gbp.rpm.intro">
<title>Introduction</title>
+
<para>
-
Git-buildpackage is a <ulink url="http://www.debian.org/">Debian</ulink>
- toolset for maintaining and building packages in/from git repositories.
- The still experimental RPM variants of the tool, extend the support
- from Debian-only to building and maintaining RPM packages, too.
- The documentation of git-buildpackage-rpm here reflects the the
-
<ulink url="gbp.html">Debian git-buildpackage documentation</>
- <!--<xref linkend="gbp">Debian git-buildpackage documentation</xref>.-->
+ Git-buildpackage is a <ulink url="http://www.debian.org/">Debian</ulink>
+ toolset for maintaining and building packages in/from git repositories.
+ The still experimental RPM variants of the tool, extend the support
+ from Debian-only to building and maintaining RPM packages, too.
+ The documentation of git-buildpackage-rpm here reflects the the
+ <ulink url="gbp.html">Debian git-buildpackage documentation</>
+ <!--<xref linkend="gbp">Debian git-buildpackage documentation</xref>.-->
</para>
+
<para>
- The RPM versions of the tools can in their current state
- do basically all the same tasks as the Debian versions, except for changelog generation.
- However, the philosophy is somewhat different in some parts. The RPM tools
- read the .spec file instead of changelog in determining packaging
- information (version number, name etc). Another clear difference is
- that &git-buildpackage-rpm; will always build in a separate build
- directory whereas &git-buildpackage; (the Debian) tool builds in the
- git working dir, by default.
- Third, conceptual, difference (for non-native packages) is that you may
- have packaging files in an orphan branch, without development sources:
- i.e. you develop code in 'patch-queue' branch that doesn't contain any
- packaging files, and, do 'pq-rpm export' to 'packaging' branch that only
- contains packaging files (.spec file, patches etc.) but no sources.
- The Debian/RPM tool equivalence is:
- <itemizedlist>
- <listitem><para>&git-buildpackage; -> RPM: &git-buildpackage-rpm;</para></listitem>
- <listitem><para>&git-import-dsc; -> RPM: &git-import-srpm;</para></listitem>
- <listitem><para>&git-import-orig; -> RPM: &git-import-orig-rpm;</para></listitem>
-
<listitem><para>&gbp-pq; -> RPM: &gbp-pq-rpm;</para></listitem>
-
<listitem><para>&gbp-clone; -> RPM: &gbp-clone; (the same tool)</para></listitem>
-
<listitem><para>&gbp-pull; -> RPM: &gbp-pull; (the same tool)</para></listitem>
- <listitem><para>&git-dch; -> RPM: not available</para></listitem>
- <listitem><para>&git-import-dscs; -> RPM: not available</para></listitem>
- </itemizedlist>
+ The RPM versions of the tools can in their current state
+ do basically all the same tasks as the Debian versions, except for changelog generation.
+ However, the philosophy is somewhat different in some parts. The RPM tools
+ read the .spec file instead of changelog in determining packaging
+ information (version number, name etc). Another clear difference is
+ that &git-buildpackage-rpm; will always build in a separate build
+ directory whereas &gbp-buildpackage; (the Debian) tool builds in the
+ git working dir, by default.
+ Third, conceptual, difference (for non-native packages) is that you may
+ have packaging files in an orphan branch, without development sources:
+ i.e. you develop code in 'patch-queue' branch that doesn't contain any
+ packaging files, and, do 'pq-rpm export' to 'packaging' branch that only
+ contains packaging files (.spec file, patches etc.) but no sources.
+ The Debian/RPM tool equivalence is:
+ <itemizedlist>
+ <listitem><para>&gbp-buildpackage; -> RPM: &git-buildpackage-rpm;</para></listitem>
+ <listitem><para>&gbp-import-dsc; -> RPM: &git-import-srpm;</para></listitem>
+ <listitem><para>&gbp-import-orig; -> RPM: &git-import-orig-rpm;</para></listitem>
+ <listitem><para>&gbp-pq; -> RPM: &gbp-pq-rpm;</para></listitem>
+ <listitem><para>&gbp-clone; -> RPM: &gbp-clone; (the same tool)</para></listitem>
+ <listitem><para>&gbp-pull; -> RPM: &gbp-pull; (the same tool)</para></listitem>
+ <listitem><para>&gbp-dch; -> RPM: not available</para></listitem>
+ <listitem><para>&gbp-import-dscs; -> RPM: not available</para></listitem>
+ </itemizedlist>
</para>
<sect1 id="gbp.rpm.repository">
<title>RPM Repository Layout</title>
+
<para>
- The required repository layout is similar to Debian: basically the only
- requirement is that non-native packages must have clean upstream sources
- in a separate branch. Other branches are:
+ The required repository layout is similar to Debian: basically the only
+ requirement is that non-native packages must have clean upstream sources
+ in a separate branch. Other branches are:
</para>
+
<itemizedlist>
- <listitem><para><option>packaging-branch</> contains packaging files (spec
+ <listitem><para>
+ <option>packaging-branch</> contains packaging files (spec
and source files, e.g. patches, needed by rpmbuild, except for the orig
tarball). This branch <emphasis>may</> contain the development sources as well
- (always true for native packages).</para></listitem>
- <listitem><para><option>upstream-branch</> contains upstream sources.
+ (always true for native packages).
+ </para></listitem>
+
+ <listitem><para>
+ <option>upstream-branch</> contains upstream sources.
This can either be a branch you import to or a branch of an upstream
- repository you pull from.</para></listitem>
- <listitem><para><option>pristine-tar-branch</> contains pristine-tar data to
- recreate the original upstream tarball from the upstream-branch.</para></listitem>
- <listitem><para><option>patch-queue/* branches</> are related to
- <option>packaging-branch(es)</>. The patch-queue branch is the upstream
- plus the patches from packaging branch applied.</para></listitem>
+ repository you pull from.
+ </para></listitem>
+
+ <listitem><para>
+ <option>pristine-tar-branch</> contains pristine-tar data to
+ recreate the original upstream tarball from the upstream-branch.
+ </para></listitem>
+
+ <listitem><para>
+ <option>patch-queue-branch(es)</> are related to
+ <option>packaging-branch(es)</>. These are also called the
+ <emphasis>development</> branhces in the RPM tools.
+ The development/patch-queue branch is the upstream
+ plus the patches from packaging branch applied. In RPM tools the
+ default branch name of the development/patch-queue branch is
+ <option>development/<packaging-branch-name></>.
+ </para></listitem>
</itemizedlist>
</sect1>
<sect1 id="gbp.rpm.workflow">
<title>RPM Workflow</title>
+
<para>
- The basic workflow is very similar to Debian:
+ The basic workflow is very similar to Debian:
</para>
+
<orderedlist>
- <listitem><para>Import a package via &git-import-srpm; OR clone from the
+ <listitem><para>
+ Import a package via &git-import-srpm; OR clone from the
distro git with &gbp-clone; if the package is already maintained with
- &git-buildpackage-rpm;.</para></listitem>
- <listitem><para>Develop, test, commit changes.</para></listitem>
+ &git-buildpackage-rpm;.
+ </para></listitem>
+
+ <listitem><para>
+ Develop, test, commit changes.</para></listitem>
<listitem><para>Once satisfied you can build the final package with
&git-buildpackage-rpm; (optionally with --git-tag to create a tag in
- git) and push it to git server.</para></listitem>
+ git) and push it to git server.
+ </para></listitem>
</orderedlist>
</sect1>
+++ /dev/null
-<chapter id="gbp.rpm.development">
- <title>Development flow</title>
-
- <sect1 id="gbp.rpm.setup.models">
- <title>Development models</title>
- <para>The &git-buildpackage-rpm; toolset basically supports three different
- models of package maintenance.</para>
- <sect2>
- <title>Native package</title>
- <para>This means that you are the upstream, there is no separate
- upstream with which you have to sync. Basically, only <option>packaging-branch</>
- is used - it contains both the source code and packaging files. No
- patches should be present as all changes can be directly committed to
- upstream (which is you). When building, &git-buildpackage-rpm; will create
- the source tarball and copy it and the packaging to the build directory.
- </para>
- </sect2>
- <sect2>
- <title>Upstream package, alternative 1: packaging and sources in the same branch</title>
- <para>This represents somewhat Debian-style package maintenance.
- All changes (packaging and source code) are done to the same branch,
- i.e., the <option>packaging-branch</>, based on the <option>upstream-branch</>.
- When package is built,
- &git-buildpackage-rpm; can automatically generate patches from
- upstream version to packaging branch head (one patch per commit).
- and modify the spec file accordingly.
- </para>
- </sect2>
- <sect2>
- <title>Upstream package, alternative 2: packaging and sources in separate branches</title>
- <para>In this model packaging files (spec and patches) are held in
- <option>packaging-branch</> and upstream sources in <option>upstream-branch</>.
- Your code development is done on the <option>patch-queue-branch</>,
- based on the <option>upstream-branch</>, which only contains source
- code but no packaging files. When building the package, &gbp-pq-rpm;
- tool is used to export patches from the patch queue branch to the
- packaging branch and edit the spec file accordingly.
- Finally, &git-buildpackage-rpm; will create the upstream source
- tarball and export it and the packaging files to the build directory,
- and, build the RPM package.
- </para>
- </sect2>
- </sect1>
-
- <sect1 id="gbp.rpm.setup.scratch">
- <title>Starting from scratch with a non-native package</title>
- <para>In this case, you most probably want to package software not yet
- found in your distro. First, create an empty repository:
- <screen>
- <command>mkdir</> mypackage
- <command>cd</> mypackage
- <command>git init</>
- </screen>
- Then, import the upstream sources, create the packaging/development
- branch and add the rpm packaging files. You have two choices:
- <orderedlist>
- <listitem><para>packaging files and development sources in the same branch
- <screen>
- <command>git-import-orig-rpm</> ../mypackage.tar.gz
- # Optionally (recommended): add gbp.conf
- <command>vim</> .gbp.conf && <command>git add</> .gbp.conf && <command>git commit</> -m"Add gbp.conf"
- # Add packaging files to source tree under subdir 'packaging'
- <command>mkdir</> packaging && <command>cd</> packaging
- <command>vim</> mypackage.spec
- <command>git add</> .
- <command>git commit</> -m"Add packaging files"
- </screen></para>
- </listitem>
- <listitem><para>development sources and packaging files in separate branches
- <screen>
- <command>git-import-orig-rpm</> --no-merge ../mypackage.tar.gz
- # Optionally (recommended): add gbp.conf
- <command>vim</> .gbp.conf && <command>git add</> .gbp.conf && <command>git commit</> -m"Add gbp.conf"
- # Add packaging files (to root of master branch)
- <command>vim</> mypackage.spec
- <command>git add </> .
- <command>git commit</> -m"Add packaging files"
- </screen></para>
- </listitem>
- </orderedlist>
- </para>
- </sect1>
-
- <sect1 id="gbp.rpm.setup.convert">
- <title>Converting an existing git repository of a non-native package</title>
- <para>In this case, you already have a git repository containing the
- upstream source, but it was created neither with &gbp-clone; nor &git-import-srpm;.
- You need to have a separate branch for upstream sources.
- If you already have that, you can simply rename that branch to the default upstream-branch:
- <screen>
- <command>$ git branch</> -m my-old-upstream-branch upstream
- </screen>
- OR just add the name of your upstream branch to gbp.conf.
- Then, you just create a packaging/development branch(es) with git and
- add packaging files to the packaging branch.
- </para>
- </sect1>
-</chapter>
-
</bookinfo>
&ch.intro-rpm;
- &ch.setup-rpm;
+ &ch.development-rpm;
&ch.building-rpm;
<appendix id="gbp.copyleft">
projects / tools / git-buildpackage.git / commitdiff