From Fedora Project Wiki
(excerpt from https://fedoraproject.org/wiki/Packaging:SourceURL#Git_Hosting_Services)
 
(update)
Line 19: Line 19:
  
 
<pre>
 
<pre>
%global commit0 40-CHARACTER-HASH-VALUE
+
%global commit 40-CHARACTER-HASH-VALUE
%global gittag0 GIT-TAG
+
%global gittag GIT-TAG
%global shortcommit0 %(c=%{commit0}; echo ${c:0:7})    [GitHub]
+
%global shortcommit %(c=%{commit}; echo ${c:0:7})    [GitHub]
%global shortcommit0 %(c=%{commit0}; echo ${c:0:11})  [Bitbucket]
+
%global shortcommit %(c=%{commit}; echo ${c:0:11})  [Bitbucket]
%global shortcommit0 %(c=%{commit0}; echo ${c:0:7})    [GitLab]
+
%global shortcommit %(c=%{commit}; echo ${c:0:7})    [GitLab]
 
</pre>   
 
</pre>   
 
                                                          
 
                                                          
Line 32: Line 32:
 
For the source tarball, you can use the following syntax:
 
For the source tarball, you can use the following syntax:
 
<pre>
 
<pre>
Source0:  https://github.com/OWNER/%{name}/archive/%{commit0}.tar.gz#/%{name}-%{shortcommit0}.tar.gz
+
Source0:  https://github.com/OWNER/%{name}/archive/%{commit}/%{name}-%{shortcommit}.tar.gz
Source0:  https://bitbucket.org/OWNER/%{name}/get/%{commit0}.tar.gz#/%{name}-%{shortcommit0}.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=%{commit0}#/%{name}-%{shortcommit0}.tar.gz
+
Source0:  https://gitlab.com/OWNER/%{name}/repository/archive.tar.gz?ref=%{commit}#/%{name}-%{shortcommit}.tar.gz
 
...
 
...
  
 
%prep
 
%prep
%autosetup -n %{name}-%{commit0}              [GitHub]
+
%autosetup -n %{name}-%{commit}              [GitHub]
%autosetup -n OWNER-%{name}-%{shortcommit0}  [BitBucket]
+
%autosetup -n OWNER-%{name}-%{shortcommit}  [BitBucket]
%autosetup -n %{name}.git                     [GitLab]
+
%autosetup -n %{name}.git                   [GitLab]
 
</pre>
 
</pre>
  
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 %{shortcommit0} macro). See [[Packaging:Naming#Pre-Release_packages|Pre-Release packages]] for details.
+
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 [[Packaging:Naming#Pre-Release_packages|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: [[Packaging:Versioning#Snapshot_packages|Snapshot packages]]. You can substitute %{shortcommit0} for the git hash in %{checkout} in that section.
+
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: [[Packaging:Versioning#Snapshot_packages|Snapshot packages]]. You can substitute %{shortcommit} for the git hash in %{checkout} in that section.
  
 
=== Git Tags ===
 
=== Git Tags ===
Line 51: Line 51:
 
<span class="plainlinks">[//git-scm.com/docs/git-tag Git tags]</span> represent a particular code point that upstream deems important; and are typically used to mark release points.
 
<span class="plainlinks">[//git-scm.com/docs/git-tag Git tags]</span> represent a particular code point that upstream deems important; and are typically used to mark release points.
  
Bitbucket uses the %{shortcommit0} 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.
+
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:
 
For the source tarball, you can use the following syntax:
 
<pre>
 
<pre>
Source0:  https://github.com/OWNER/%{name}/archive/GIT-TAG/%{name}-%{version}.tar.gz
+
Source0:  https://github.com/OWNER/%{name}/archive/%{gittag}/%{name}-%{version}.tar.gz
Source0:  https://bitbucket.org/OWNER/%{name}/get/GIT-TAG.tar.gz#/%{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
 
Source0:  https://gitlab.com/OWNER/%{name}/repository/archive.tar.gz?ref=GIT-TAG#/%{name}-%{version}.tar.gz
 
...
 
...
  
 
%prep
 
%prep
%autosetup -n %{name}-%{version}              [GitHub]
+
%autosetup -n %{name}-%{gittag}              [GitHub]
%autosetup -n OWNER-%{name}-%{shortcommit0}    [BitBucket]
+
%autosetup -n OWNER-%{name}-%{shortcommit}    [BitBucket]
%autosetup -n %{name}.git                     [GitLab]
+
%autosetup -n %{name}.git                     [GitLab]
 
</pre>
 
</pre>
  
Line 70: Line 70:
 
Some projects may use the <span class="plainlinks">[//git-scm.com/docs/git-submodule Git submodule]</span> 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.
 
Some projects may use the <span class="plainlinks">[//git-scm.com/docs/git-submodule Git submodule]</span> 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, commit0, gittag0 and shortcommit0; you will use Source1, commit1, gittag1 and shortcommit1.
+
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 Source, commit, gittag and shortcommit; you will use Source1, commit1, gittag1 and shortcommit1.
 
An example %prep section (assuming the use of Commit Revision) would be:
 
An example %prep section (assuming the use of Commit Revision) would be:
  
 
<pre>
 
<pre>
 
%prep
 
%prep
%autosetup -n %{name}-%{commit0} -a 1              [GitHub]
+
%autosetup -n %{name}-%{commit} -a 1              [GitHub]
%autosetup -n OWNER-%{name}-%{shortcommit0} -a 1    [BitBucket]
+
%autosetup -n OWNER-%{name}-%{shortcommit} -a 1    [BitBucket]
%autosetup -n %{name}.git -a 1                     [GitLab]
+
%autosetup -n %{name}.git -a 1                     [GitLab]
rmdir SUBMODULE                                 [Remove SUBMODULE]
+
rmdir SUBMODULE                                   [Remove SUBMODULE]
mv -f %{name}-%{commit1} SUBMODULE               [Move SUBMODULE TO %{name}]
+
mv %{name}-%{commit1} SUBMODULE                   [Move SUBMODULE TO %{name}]
 
</pre>   
 
</pre>   
 
   
 
   
If for some reason that isn't feasible, an alternative is to rebuild the tarball prior to it's 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 [[#RevisionControl|Using Revision Control]] section.  The following is an example specific to Git submodules:
+
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 [[#RevisionControl|Using Revision Control]] section.  The following is an example specific to Git submodules:
  
 
<pre>
 
<pre>

Revision as of 20:49, 21 July 2017

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 Source: 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 Source, commit, gittag and shortcommit; you will use Source1, commit1, gittag1 and shortcommit1. An example %prep section (assuming the use of Commit Revision) 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.