Simple Use of Github for Distfiles

What using GitHub affects

The only part of building a port that using GitHub affects is the fetch phase -- actually pulling down the distribution files from GitHub. Once you've got all the necessary sources, the rest of building the port is exactly the same as it would be for using any other download location.

What is the ''simple'' case?

The FreeBSD ports can not only use GitHub, but can adapt to just about any of the weird and wonderful choices made by project authors. Consequently there are a lot of different GitHub-related settings available to use in a port -- all comprehensively documented in the Porter's Handbook -- but it can be confusing to the uninitiated.

If the following conditions are fulfilled, what you need to add to your port's Makefile is very simple:

Very many GitHub projects match this pattern, and consequently this is the most popular pattern you will find for GitHub-using ports.

Makefile Variables

You will need to set the following in your port:








Typically v





You will not need either of:



An Example

Let us consider the `databases/pg_citus` port as an example of the 'simple' pattern.

PORTNAME=       citus
CATEGORIES=     databases


USE_GITHUB=     yes
GH_ACCOUNT=     citusdata

The GitHub page for this project is and if we examine their release page we can see that they use release tags incorporating the software version number, like `v9.3.0`. These correspond to the Makefile settings:
                      ^         ^
                      |         PORTNAME


Slightly Less Simple Ports

The next largest grouping of GitHub-using ports are those where either the project naming or versioning doesn't quite match the simple pattern. If PORTNAME doesn't match the project name, override the defaults by setting GH_PROJECT to the project name. Similarly if the release tag isn't suitable as PORTVERSION you can frequently use DISTVERSION instead, in combination with DISTVERSIONPREFIX or (more rarely) DISTVERSIONSUFFIX. If that doesn't work, then you can set GH_TAGNAME directly.

Also still in the relatively simple category are the cases where upstream has committed an important bug fix but has not yet released a new version with the fix. One approach here (there are other alternatives) is to set GH_TAGNAME to the SHA hash of the commit fixing the problem, or the 6 character shortened hash.

More Complicated Ports

More advanced GitHub usage usually involves pulling down more than one distfile from GitHub, in many cases because the upstream authors have used git submodules to pull in sources from a different project. Software written in the go language has a certain reputation for doing this extensively. In this case, you'ld use GH_TUPLE -- the `www/gitlab-pages` port is an example.

Finally there is perhaps the zenith (or maybe nadir) of complexity: `www/nginx` which mixes not only numerous different distfiles pulled from projects all over GitHub, but uses OPTIONS to make compiling most of the available extensions configurable.

If you're still unsure

It can be a bit of a pitfall when looking for something to base your port on that you end up copying a bad example. Prefer copying from ports that have a named maintainer, and that are being actively developed and are up-to-date with their upstream sources.


This page is based on a reply I made in a thread on the freebsd-ports mailing list. Thanks to Adam Weinberger for suggesting I write this Wiki entry.


Ports/SimpleGithub (last edited 2020-05-25T16:17:19+0000 by MatthewSeaman)