From Fedora Project Wiki

< User:Zbyszek

Revision as of 19:15, 3 August 2017 by Zbyszek (talk | contribs) (→‎Git Hosting Services: fix one more Source reference)

Git Hosting Services

If the upstream does create tarballs you should use them as tarballs provide an easier trail for people auditing the packages.

Git web-based hosting services provide a mechanism to create tarballs on demand, either from a specific commit revision, or from a specific tag. If the upstream does not create tarballs for releases, you can use this mechanism to produce them.

The full 40-character hash and associated git tag may be obtained by issuing the following git command:

git ls-remote https://HOSTING-SERVICE/OWNER/%{name}.git

HOSTING-SERVICE:  name of the service, i.e. "github.com", "bitbucket.org", "gitlab.com", etc.
OWNER:            username for the repository owner

You may also obtain the 40-character hash and associated git tag via the web-interface of the HOSTING-SERVICE, or by cloning the repository and issuing the git show-ref command.

Once the commit hash and git tag are known, you can define them in your spec file as follows:

%global commit 40-CHARACTER-HASH-VALUE
%global gittag GIT-TAG
%global shortcommit %(c=%{commit}; echo ${c:0:7})    [GitHub]
%global shortcommit %(c=%{commit}; echo ${c:0:11})   [Bitbucket]
%global shortcommit %(c=%{commit}; echo ${c:0:7})    [GitLab]

Note that the numeric identifier after commit, gittag and shortcommit matches the associated identifier of the Source0: tag.

Commit Revision

For the source tarball, you can use the following syntax:

Source0:  https://github.com/OWNER/%{name}/archive/%{commit}/%{name}-%{shortcommit}.tar.gz
Source0:  https://bitbucket.org/OWNER/%{name}/get/%{commit}.tar.gz#/%{name}-%{shortcommit}.tar.gz
Source0:  https://gitlab.com/OWNER/%{name}/repository/archive.tar.gz?ref=%{commit}#/%{name}-%{shortcommit}.tar.gz
...

%prep
%autosetup -n %{name}-%{commit}              [GitHub]
%autosetup -n OWNER-%{name}-%{shortcommit}   [BitBucket]
%autosetup -n %{name}.git                    [GitLab]

If the release corresponds to a git tag with a sane numeric version, you must use that version to populate the Version: tag in the spec file. If it does not, look at the source code to see if a version is indicated there, and use that value. If no numeric version is indicated in the code, you may set Version to 0, and treat the package as a "pre-release" package (and make use of the %{shortcommit} macro). See Pre-Release packages for details.

Alternately, if you are using a specific revision that is either a pre-release revision or a post-release revision, you must follow the "snapshot" guidelines. They are documented here: Snapshot packages. You can substitute %{shortcommit} for the git hash in %{checkout} in that section.

Git Tags

Git tags represent a particular code point that upstream deems important; and are typically used to mark release points.

Bitbucket uses the %{shortcommit} identifier as part of the archive directory structure; regardless of whether you use git tag or Commit Revision to retrieve it. This is shown in the %prep section example.

For the source tarball, you can use the following syntax:

Source0:  https://github.com/OWNER/%{name}/archive/%{gittag}/%{name}-%{version}.tar.gz
Source0:  https://bitbucket.org/OWNER/%{name}/get/%{gittag}.tar.gz#/%{name}-%{version}.tar.gz
Source0:  https://gitlab.com/OWNER/%{name}/repository/archive.tar.gz?ref=GIT-TAG#/%{name}-%{version}.tar.gz
...

%prep
%autosetup -n %{name}-%{gittag}               [GitHub]
%autosetup -n OWNER-%{name}-%{shortcommit}    [BitBucket]
%autosetup -n %{name}.git                     [GitLab]

Git Submodules

Some projects may use the Git submodule capability. If so, please note that the submodule will not be included in the tarball. Instead, it will appear in the tarball as an empty directory. In this situation, you will need to manually incorporate the submodule into the project.

The simplest method is to incorporate the submodule within the %prep section of the spec file. In this instance you will follow the preceding instructions to obtain the tarball for the submodule project. Instead of Source0, %commit, %gittag and %shortcommit; you will use Source1, %commit1, %gittag1 and %shortcommit1. An example %prep section would be:

%prep
%autosetup -n %{name}-%{commit} -a 1               [GitHub]
%autosetup -n OWNER-%{name}-%{shortcommit} -a 1    [BitBucket]
%autosetup -n %{name}.git -a 1                     [GitLab]
rmdir SUBMODULE                                    [Remove SUBMODULE]
mv %{name}-%{commit1} SUBMODULE                    [Move SUBMODULE TO %{name}]

If for some reason that isn't feasible, an alternative is to rebuild the tarball prior to its inclusion in the spec file. This involves cloning the project, issuing the Git commands to incorporate the submodule, then building a tarball of the newly created project directory structure. You will then need to comment as described in the Using Revision Control section. The following is an example specific to Git submodules:

# The source of this package was pulled from upstreams's vcs.
# Use the following command to generate the tar ball:
# git clone --recursive http://HOSTING-SERVICE/OWNER/%{name}.git
# tar cvjf %{name}-%{version}.tar.gz %{name}/

Keep in mind that the version specified reflects that of the project and NOT the submodule.