# GitX: a native macOS git client, its build system and its signing rules

> GitX is a macOS native graphical client for git, in Objective-C and licensed under GPL version 2, whose repository history is a consolidation of several community forks. It installs from a Homebrew cask or a release archive, and building it from source means bootstrapping submodules, understanding the hardened runtime rules and producing a Dev.xcconfig for your own signing identity.

**gitx/gitx** — The best fork of the best lightweight, visual git client for macOS.

- Repository: https://github.com/gitx/gitx
- Stars: 916 · Forks: 98
- Language: Objective-C
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/gitx-gitx

## A client whose history is a consolidation of forks

GitX is an OS X, macOS, native graphical client for the git version control system. The project description calls itself the best fork of the best lightweight visual git client for macOS, and the README explains what that means.

It says GitX has a long history of various branches and versions maintained by various people over the years, and that this GitHub organisation and repository are an attempt to consolidate and move forward with a current, common, community-maintained version.

That is a rare and slightly awkward position to be in. A graphical git client for macOS has been forked several times over more than a decade, and the people behind those forks disagreed often enough that the ecosystem ended up with several near-parallel applications. Consolidating them means the project now carries the weight of being the successor rather than the origin, and the source of truth is whichever branch a contributor happened to start from.

The implementation is Objective-C, the licence is GPL version 2 with the text in the COPYING file at the root of the repository, and the project ships as a macOS application with a Staging View and a History View, plus a command line tool, the askpass helper, and separate entitlement files for the app, the CLI tool and the helper.

The maintenance pace is quick. The recent releases are 1.7.1 from 2026-10-05, 1.7 from 2026-10-03 and 1.6 from 2026-09-19, and the last push was on 2026-10-17.

## Install with a cask, or take the release archive

The Homebrew route is a single command.

```bash
brew install --cask gitx
```

The README explains what that does, and the explanation is the useful part. It picks the build for your Mac, it puts the gitx command-line tool on your PATH, and it lets brew upgrade keep it up to date. The command line tool on the PATH is what makes the cask preferable to a dragged application bundle, because the helper the app uses to ask for credentials has to be reachable from the shell.

The alternative is to download the latest release from the Releases page, extract it and move it to your Applications folder. One detail matters here: for Apple Silicon, the M1 and M2 processors, you should use the arm64 release.

That instruction still matters even with the cask available, because it applies to anyone who grabs a build by hand, and because it is the kind of thing that produces a confusing failure on a modern Mac if the wrong architecture is chosen.

Two further links round out the installation section: the release download page, and a pointer to how to build in Xcode for people who would rather compile it themselves.

## make bootstrap is the first thing a fresh clone needs

Building from source starts with one command that is easy to miss, because it is not the build itself.

In a fresh clone you run make bootstrap before the first build, in Xcode or on the command line. What it does is check out the submodules and build the objective-git and libgit2 dependencies the app links against. If it stops partway, on a dropped connection for instance, you run it again.

That last sentence is practical advice from someone who has watched this fail. The bootstrap step fetches and builds the native dependencies, so it is the step that touches the network, and it is the step that can be interrupted.

After that, the command line workflow is a set of Makefile targets. The README names make build, make unit-test and make dmg as the common ones, make help lists them all, and ARCH=x86_64 selects an x86 build on an Intel Mac or for a cross build. From a fresh clone, make bootstrap run builds the app and opens it.

The reason the project bothers with a Makefile at all, in a world of Xcode projects, is stated in the file itself. The targets deliberately mirror the steps in the GitHub Actions workflow BuildPR.yml so the two stay in sync, with a comment naming the CI step each target matches, and a warning that changing a command in one means changing it in the other.

## The hardened runtime is what makes signing your problem

Code signing on macOS is where contributors get stuck, and the README and Makefile together explain the rules clearly.

Debug builds, from Xcode or from make run, are signed ad-hoc and need no setup at all. Signing with your own certificate is only needed for a build with the hardened runtime turned on, and for the make dmg-signed target.

The reason is spelled out in the Makefile comments. Without a Dev.xcconfig file the build is signed ad-hoc, and the hardened runtime rejects that, which leaves the app unable to load its own frameworks. So dmg builds with the hardened runtime off and stays runnable either way, while archive and dmg-signed keep the hardened runtime on and want a real identity.

The Dev.xcconfig file lives at the project root and is git ignored. If you do not have a development certificate, the README walks through creating one: open Xcode, add your Apple ID in Settings and Accounts, pick the team with Personal Team in the name, use Manage Certificates, and add an Apple Development certificate.

Once the certificate exists, make Dev.xcconfig writes the file for you, reading the team ID and the certificate name off the certificate itself, and it says what is missing if it cannot. It never overwrites a file that is already there, so after renewing a certificate you run FORCE=1 scripts/make-dev-xcconfig.sh. If your keychain holds certificates for more than one team, pick one with TEAM=YOUR_TEAM_ID make Dev.xcconfig.

## The Makefile is a map of CI, including the parts CI does not run

The Makefile header is a short essay on how the project keeps its local workflow and its continuous integration honest, and it documents the target to CI step mapping directly.

The table in the comments is the useful part. deps corresponds to the pre build step, unit-test to Run unit tests, ui-test to Run tests, archive to Build project, and package-signed to Prepare artifact.

Three subtleties follow from it. The pre-build target is deps plus the submodule checkout that CI gets from its own checkout step, which is why a fresh local clone wants pre-build while CI wants deps. The all-tests target matches no CI step, because it tests the whole scheme and repeats the unit tests CI has already run in its own step, and it exists for a local run of everything in one command.

And then there is the exclusion. The format, format-check and format-warning targets exist locally but not in CI, because CI has no clang-format and a different version of it may format the same code another way. The project would rather have a formatting difference than a CI job that fails on a tool version, and saying so in the file is the kind of decision that saves an argument later.

The build variables tell you the rest of the shape: the workspace is GitX.xcworkspace, the scheme is GitX, the destination is platform=macOS with the architecture variable, and the outputs are a GitX.app bundle, a GitX.xcarchive, and a disk image named GitX with the architecture in the file name.

## What the tree says about the application

The repository layout is the usual shape of a long-lived native macOS application, and reading it tells you where the effort goes.

Classes holds the Objective-C sources, Resources the assets the app loads, External the vendored dependencies, and Site the files for the project website. The Xcode project and workspace sit at the top level, with GitX.xcodeproj and GitX.xcworkspace, and there are two test targets, GitXTests and GitXUITests, so unit tests and interface tests are separated.

Three entitlement files are present, GitX.entitlements, cli tool.entitlements and gitx_askpasswd.entitlements, one for the app, one for the command line tool and one for the credential helper. The separate askpass helper is the reason the cask puts gitx on your PATH: the application shells out to that helper to prompt for a password, and the helper has to live somewhere the shell can find.

Two directories suggest a project that pays attention to its own documentation. There is a screenShotScript, alongside a SyntaxHighlighter-missing folder and a git-diff-image directory, which read like tooling for producing the images used in the README. There is a docs directory and an assets directory for the screenshots themselves, and a scripts directory holding the shell helpers referenced by the signing instructions.

The code style files are at the root too, a .clang-format and an .editorconfig, which is the minimum for a project where contributions come from many hands.

## Continuous integration on a donated Mac, and a GPL licence to read

The Apple Silicon section of the README explains how CI is paid for, and the answer is specific rather than aspirational. The project is supported by the MacStadium Open Source Developer Program, with a free Mac mini provided for their CI.

That detail explains several things about the project. It is why there is a single build machine rather than a matrix of architectures, why the arm64 build exists alongside the x86 one, and why the Apple Silicon instructions are as prominent as they are. It is also a small dependency worth knowing about, since a hosted CI machine for a macOS-only project is not free, and the project is candid about where it comes from.

The licence is GPL version 2, stated in the README with a pointer to the attached COPYING file. The licence field on the repository carries a custom classification that GitHub cannot label, so the COPYING file is the text that governs. For a community continuation of an older open source application, GPLv2 is the term the project has always carried, and a fork inherits it.

The release numbering is plain, 1.6 then 1.7 then 1.7.1, and the dates are close together, 1.6 on 2026-09-19, 1.7 on 2026-10-03 and 1.7.1 on 2026-10-05, with the last push on 2026-10-17. A project that had been dormant for years is now shipping small increments regularly, which is the behaviour of a consolidated fork that has found an active maintainer.

## Conclusion

Adopt GitX if you want a visual git client that is native to macOS rather than a cross platform tool running under a translation layer, and if you are comfortable that it only exists for macOS. Do not adopt it if you need the same client on Linux or Windows, because the project is macOS only, and read the licence before you fork it, since it is GPL version 2 and the COPYING file governs. Before the first build, run make bootstrap on a fresh clone and again if it stops partway, keep the architecture in mind with ARCH=x86_64 for an Intel or cross build, and read the signing section before packaging anything, because without a Dev.xcconfig the hardened runtime rejects the ad-hoc signature and only the dmg target stays runnable.

## FAQ

### How do I install GitX on macOS?

Run brew install --cask gitx, which picks the build for your Mac, puts the gitx command-line tool on your PATH and lets brew upgrade keep it current. You can also download the latest release from the Releases page, extract it and move it to your Applications folder, using the arm64 release on Apple Silicon.

### What does make bootstrap do in a fresh GitX clone?

It checks out the submodules and builds the objective-git and libgit2 dependencies the app links against, and it has to run before the first build in Xcode or on the command line. If it stops partway, for instance on a dropped connection, you run it again.

### Do I need a signing certificate to build GitX?

No for debug builds, which are signed ad-hoc and need no setup. A certificate is only needed for a build with the hardened runtime enabled and for make dmg-signed. The make Dev.xcconfig target writes a Dev.xcconfig file at the project root from your certificate, and the tests need no identity at all.

### How do I make an x86_64 build of GitX?

Pass ARCH=x86_64 to the make targets. The Makefile sets ARCH from uname -m by default, and the same variable names the disk image output, GitX with the architecture in the file name.

### What licence is GitX released under?

GitX is licensed under GPL version 2, and the licence text is in the COPYING file at the repository root. The licence field on the repository carries a custom classification that GitHub cannot label.

## Sources

- [gitx/gitx on GitHub](https://github.com/gitx/gitx)
- [Issues](https://github.com/gitx/gitx/issues)
- [README](https://github.com/gitx/gitx/blob/master/README.md)
- [Releases](https://github.com/gitx/gitx/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gitx-gitx