Full Git Integration

Basic mode

GitLode is a Mac App Store app, so it runs inside the App Sandbox. The App Sandbox is a macOS restriction on the files and programs that an app can use. The restriction also applies to the programs that the app starts, including Git.

Basic mode is the default. In Basic mode, GitLode runs Apple's Git from the Command Line Tools or Xcode, inside the App Sandbox. If you have neither, open Terminal and run xcode-select --install.

In Basic mode, Git cannot run these programs:

• Hooks.
• Git LFS.
• Programs that sign commits, such as GPG or 1Password.
• Most credential helpers, such as gh or Git Credential Manager.
• External diff and merge tools.

Before an operation that would run a hook, GitLode names the hooks and asks what to do. Choose Install Full Git Integration…, Continue Without Hooks, or Cancel. GitLode never skips a hook without asking.

If Git fails because of one of these limits, GitLode shows an alert that explains the limit. To install Full Git Integration from the alert, click Install Full Git Integration….

Git can use your Git configuration and SSH settings only if GitLode can read your home folder. Without that access, SSH uses the keys in the macOS ssh-agent, and GitLode keeps its own list of known hosts. See Folder access.

The helper script

Full Git Integration is optional. Install it if you use hooks, commit signing, Git LFS, a credential helper, or a diff or merge tool.

GitLode installs one shell script, gitlode-bridge, in ~/Library/Application Scripts/com.pocketarc.GitLode. macOS runs scripts in that folder outside the App Sandbox. GitLode starts Git through the script, so Git runs as it does in Terminal:

• GitLode uses the first git in your shell's PATH, or the path that you set in Settings > Tools.
• Git uses your Git configuration, credentials, and SSH settings.
• Git runs your hooks, your signing program, and Git LFS.
• Git opens your diff and merge tools.

The script reads the environment of your login shell, so Git gets the same PATH and environment variables as in Terminal. Then the script starts Git with the arguments from GitLode.

A sandboxed app cannot write to its Application Scripts folder until you choose that folder in a panel. For this reason, you confirm the installation in a panel.

Install Full Git Integration

1. Open Settings with Command+Comma, then click Tools.
2. Next to Git integration, click Install….
3. In the panel, keep the folder that is open and click Install.

The status in Settings > Tools changes to Full Git Integration. You can also click Install Full Git Integration… on the sheet that appears when you first open GitLode.

Update or remove the script

A new version of GitLode can include a new version of the script. When an update is available, GitLode shows it in Settings > Tools. Click Update…, then click Update in the panel. If the installed script is for a different version of GitLode, GitLode uses Basic mode until you update the script.

To remove the script, click Remove… in Settings > Tools, then click Remove in the panel. GitLode returns to Basic mode.