Reference

Configuration Partly available

GitMaster keeps little configuration of its own. Git options and app preferences both live in Git's configuration files, as gitmaster.* keys, so they can be tracked with your dotfiles and overridden per repository. State about a repository stays in that repository's Git directory. GitMaster never writes into the working tree of a repository.

Where GitMaster stores data#

GitMaster keeps its files in three places: your user config directory, your user data directory, and the Git directory of each repository. Nothing is written into a repository's working tree, so no .gitignore entry is needed and no file appears as changed.

User config directory#

User data directory#

A repository whose folder no longer exists is dropped from the recent list.

Inside each repository#

GitMaster keeps per-repository state in .git/gitmaster/, inside the Git common directory. In a linked worktree, that is the common directory shared by all worktrees of the repository, so every worktree sees the same state. To find it, run git rev-parse --git-common-dir.

The Git command log, the list of Git commands with side effects that the Git commands panel shows, is kept in memory only. It keeps the last 1000 commands and is lost when the app closes.

Preferences#

GitMaster keeps its own preferences as gitmaster.* keys in Git's configuration. Put your base values in ~/.gitconfig, so they are tracked with the rest of your dotfiles, and override them in one repository with git config or by editing its .git/config. Git's rules apply: the system file, then ~/.gitconfig, then the repository's .git/config, then the worktree's config, and each later layer wins. include and includeIf work too, so a work repository can take a different set from a personal one.

# ~/.gitconfig
[gitmaster]
	diffLayout = split
[gitmaster "threads"]
	maxResultBytes = 131072
	redactPath = .env
	redactPath = secrets/**
[gitmaster-redact "acme-token"]
	regex = acme_[A-Za-z0-9]{32}

git config --global gitmaster.diffLayout split   # for every repository
git config gitmaster.threads.capture false       # for this repository only

When you change a preference in the app, it is written to ~/.gitconfig (git config --global). Only a value that differs from the default is stored, and a value that goes back to its default is removed, so the file holds only what you chose. The app never changes a repository's .git/config, so an override you wrote there stays and wins. A repository's preferences are read when its window opens.

The agent integration reads these keys each time a hook runs, from the repository the event comes from, so a change applies to the next event. A pattern <name> uses letters, digits, - and _, and it must not repeat a built-in or another pattern. The regular expression has the syntax of Rust's regex crate and matches in linear time, so a pattern cannot make the hook hang. A pattern that is not valid pauses capture in every repository until it is fixed. See Secrets.

Rules for lists and patterns:

• A key that can be set more than once adds up across the layers, as Git's own lists do. A repository adds its entries to the global ones.
• An empty value clears what the layers below it set. redactPath = in a repository removes the global paths; add your own after it. A single redactPath = in ~/.gitconfig means no paths at all.
• A pattern whose regex is empty is dropped, so a repository can turn off a global pattern with [gitmaster-redact "acme-token"] and regex =.
• Git reads a backslash in a value as an escape. Write \\d for the regular expression \d, or let git config gitmaster-redact.acme.regex '\d+' write it for you.
• A value that is not valid, such as maxResultBytes = lots, reads as the default.

Git configuration keys#

GitMaster reads Git's own configuration through git, so Git's scope rules apply. A key set in ~/.gitconfig applies to every repository, and a key set in .git/config applies to one repository only. The Scope column says where a key can be set: Any means global or repository.

The branch.<name>. keys belong to stacks, which is a preview feature. See Preview features.

Environment variables#

Login-shell PATH#

A window opened from a desktop launcher, the Finder or the Dock starts with a minimal PATH. Git and the tools your shell profile adds, such as Homebrew's, may then not be found. To avoid this, GitMaster reads the PATH of your login shell once, in the background, when the app starts:

1. GitMaster runs the shell named by SHELL as a login, interactive shell that prints its environment.
2. It waits up to 10 seconds. A shell that takes longer is stopped.
3. If the shell prints a PATH, Git and the other programs GitMaster starts after that point run with it. These are the file watcher and the programs that workflows start with ctx.exec.

Programs started before the PATH is read use the PATH the app started with. If SHELL is not set, the shell does not answer in time, or it prints no PATH, GitMaster keeps the PATH it started with. GitMaster does not change its own environment variables to do this.

Preview features#

Some areas are finished in the code but not yet part of the release. A preview feature is hidden in the release build. Each one has its own environment variable, which turns it on or off when GitMaster starts:

The name of the variable is the id of the feature in capitals, with - replaced by _.

Values#

The value is not case sensitive, and spaces around it are ignored. A value that is not in this table prints a warning on stderr, and the default of the build applies. A variable that starts with GITMASTER_ENABLE_ and names no feature prints a warning and has no effect. Each variable changes only its own feature.

Build defaults#

A release build has every preview feature off. A build made with make build, make run or make install has every preview feature on. The variables override these defaults.

Examples#

Turn stacks on in the release build:

GITMASTER_ENABLE_STACKS=1 gitmaster

Turn the conflict resolver off in your own build, to see what users get:

GITMASTER_ENABLE_CONFLICT_RESOLVER=0 gitmaster

Check which preview features are on with gitmaster --version. When one or more are on, it prints a second line, preview features:, followed by their ids, such as preview features: stacks. See Command line.

Settings dialog#

Open the settings dialog with Ctrl+, (⌘, on macOS), with Open Settings in the command palette, or with the gear button at the bottom of the window. The dialog is centered over the window, and the rest of the window is dimmed. Close it with Esc, a click outside it, or its close button. The categories are on the left, and the form for the selected category is on the right.

Changes apply as you make them, and there is no Save button. A value is saved when you change it, and a text field is saved when it loses focus. A value that is not valid is flagged inline and is not saved. Each change goes to the right place:

• Git options go to Git's configuration. The scope selector sets where they go: Global writes to ~/.gitconfig, and This Repository writes to .git/config.
• App preferences go to ~/.gitconfig as gitmaster.* keys, whatever the scope selector says.
• Workflow reviews and automatic approvals go to your user data directory.
• Nothing is written to the working tree.

General#

Git & Identity#

Worktrees#

Diff & Files#

Stacks & Restack#

Conflict Resolver#

MCP & Agents#

The MCP server is started by your agent with gitmaster mcp, so it has no switch, socket or token to set. Which tool calls ask for your approval is set in your agent's permissions. See MCP server.

Threads#

The settings dialog is not available yet, so these fields are edited today in Threads Settings…, which has the same fields.

Reviewers#

Local Review#

Workflows#