This portgroup greatly simplifies the porting of software hosted on GitHub. Provided a GitHub repository author follows common GitHub practices, a port can be almost fully configured simply by declaring the repository coordinates. The github portgroup is indeed capable of configuring, amongst other things:

The main port configuration is triggered by the usage of the github.setup keyword:

PortGroup           github 1.0
github.setup        author project version [tag_prefix]

By default, the port name will be set to the GitHub project name (+project+) and version will be set to the GitHub project +version+. The port name can be overridden by using the name keyword.

The tag_prefix is optional, and it’s used to specify a prefix to use when constructing the tag name. If, for example, the project uses tags such as +v1.0.0+, then the tag_prefix should be set to +v+, as in the following example:

github.setup        author project version v

GitHub, and as a consequence the github portgroup, offers multiple mechanisms to get a distfile:

The default behaviour of the portgroup is using GitHub automatically generated distfile from a git commit or tag. However, the best practice should be using a GitHub release.

The default behaviour of the github portgroup is leveraging GitHub’s ability to create a distfile from a git tag or commit. In this case, the distname is irrelevant and should not be set.

If the project’s developers do not tag their releases, they should be encouraged to do so. Until they do, or in the case in which an untagged development version has to be used, port maintainers have the possibility of specifying a git commit hash and manually set the version field. If the project does not assign version numbers the port maintainer has to define one. Such versions typically format the date of the chosen commit using the YYYYMMDD pattern. If, for example, the port maintainer decides to use a changeset with the hash +0ff25277c3842598d919cd3c73d60768+, committed on April 1, 2014, then the following would be used:

github.setup        someone someproject 0ff25277c3842598d919cd3c73d60768
version             20140401

The github portgroup allows maintainers to easily configure the distfiles when the project uses GitHub releases. A release is the best distfile candidate, and project maintainers should be encouraged to use them. To enable this feature, the following keyword must be used:

github.tarball_from releases

By default, the github portgroup sets distname to:

distname            ${github.project}-${github.version}

However, GitHub does not enforce any rule for release distfiles, so port maintainers may need to override the distname as they would do for other ports.

Older projects use the discontinued downloads service. New GitHub downloads can no longer be created, but old ones are still available.

If the project doesn’t have GitHub releases but does have GitHub downloads, they can be used using the following keyword:

github.tarball_from downloads

Since GitHub doesn’t enforce any naming rules for downloads, the portgroup can only provide a sensible default value for +distname+, which can be overridden if necessary.

Further still, many Github projects have automatically-generated archive URLs that can be used for downloading distfiles. This can be enabled via archive as follows:

github.tarball_from archive

If the project uses git submodules, some projects' tag- or commit-based distfiles will not contain all the necessary files. Once again, the best distfile candidate (if available) is a distfile from GitHub releases, as described in the previous sections. However, in the case a project doesn’t provide any other alternative, a project using submodules can be successfully retrieved by fetching the sources using git and then using a post-fetch to initialize the submodules:

fetch.type          git

post-fetch {
    system -W ${worksrcpath} "git submodule update --init"
}