There is an elegant way to link from the wiki and bug tracker called Trac to GitHub by means of changeset links. Unfortunately, Trac’s documentation on WikiFormatting and on TracLinks does not currently describe this. But one project which I use, MacPorts, uses Trac to track MacPorts bugs and to host wiki documentation. They prefer that contributors use these changeset links rather than URLs when referring to MacPorts on GitHub. So, this is the documentation for these changeset links, in a form which I wish was in the main Trac documentation. It is here to remind me. Maybe it will also help others searching for how to do this.

On Github, MacPorts is at https://github.com/macports/ . There are several repositories, but three are most important: macports-ports (the code of the ports), macports-base (the source code of the command-line client), and macports-guide (the source which compiles to the MacPorts Guide).

Each change to the GitHub content is referred to as a commit. Each commit is identified by a 40-digit hexadecimal number, generated by GitHub’s git version control system. This number is known as a SHA hash, or SHA for short. If you and I each have a copy of the same repository, a given SHA will refer to the same commit for each of us, but no other commit in that repository, nor in any other, should have the same SHA. (Let me know if you find an exception.) An example SHA is bd5d6800828a3dcda1b65f3999fa748a365b168e.

GitHub has URLs for each commit, made up of the repository name and the SHA, e.g. https://github.com/macports/macports-ports/commit/bd5d6800828a3dcda1b65f3999fa748a365b168e.

In MacPorts bug tickets, it is common to refer to commits on GitHub. The MacPorts instance of Trac is set up to interpret a certain changeset syntax as linking to MacPorts repositories on GitHub. In fact, MacPorts prefers the changeset syntax instead of a plain URL link for this case.

The syntax is:
[changeset:<commit SHA>/<repository name> [optional link text] ]

So, for the commit URL above, the preferred link in a MacPorts Trac ticket or wiki page is: 

[changeset:bd5d6800828a3dcda1b65f3999fa748a365b168e/macports-ports commit bd5d680]

This displays as commit bd5d680. The link text, “commit bd5d680“, follows the common practice of abbreviating git SHAs to 7 digits. Other link text may work better in your situation.

Without the link text, the link is: 

[changeset:bd5d6800828a3dcda1b65f3999fa748a365b168e/macports-ports]

It displays as bd5d6800828a3dcda1b65f3999fa748a365b168e/macports-ports . This is valid, but verbose. Provide link text, and be more concise.

Git has a convention of abbreviating commit SHAs to a few leading digits, typically 7. This abbreviation is usually long enough to be unique within a repository, but short enough to be more convenient. It turns out that GitHub handles URLs with abbreviated SHA prefixes, and that Trac converts changeset links with abbreviated prefixes into the corresponding abbreviated URL. So, [changeset:bd5d680/macports-ports] is also usable — until another commit with the same abbreviated prefix appears.

I have added both quick hints and a full description of GitHub changeset links in MacPorts Trac to the documentation there, as a change to the WikiFormatting wiki page, as a change to the TracLinks wiki page, and as a change to the MacPorts Guide documentation itself. The changes to the wiki pages may get overwritten in time. The change to the Guide may not be incorporated for a while. But seeds are planted.

Seeds are also planted here. Enjoy.

No Comments »