Troubleshooting

Start with the error code in the notice. The application maps Git failures onto stable codes, and the same code appears in Git output. If the message does not explain the cause, the sections below cover the usual ones.

Git was not found

The application runs the system git binary. Without it, no repository can be opened.

1. Check that git --version works in a terminal.
2. If it does, the GUI may not see your shell PATH — common with Homebrew on macOS and with version managers. Open Settings → Git, set an absolute path to the binary, and press Test.
3. Settings → General → Check GUI PATH compares the application’s PATH with the login shell and can copy the missing entries.

A repository opened before Git was configured has to be reopened after the path is fixed.

Lock files and “another Git process”

Git refuses to write while a lock file exists. The usual cause is a Git process that is still running, or one that was killed and left .git/index.lock behind.

• If a Git process is genuinely running (a rebase in a terminal, a hook, an IDE), wait for it to finish.
• If nothing is running, use Clear locks. It lists the lock files found in the repository and deletes them only after confirmation.
• A batch operation that was interrupted also leaves a journal. The status bar reports it, and Retry failed replays only the paths that failed, after checking for locks.

Do not delete .git/index.lock by hand while another process is running; that is how an index gets corrupted.

Huge repositories

The application bounds every read so a large repository cannot freeze a window.

If a repository feels slow:

• Turn off auto-fetch if the remote is far away.
• Narrow the history with a branch filter or a search term instead of scrolling.
• Run Repository health to find a huge blob, a shallow clone or a missing LFS object.
• Use a sparse checkout for a monorepo you only partly need.

Commit signing fails

A signing failure is reported as git_signing, with a more specific code when the cause is known (missing key, key outside the repository, invalid key, unsupported format).

• Check the format: OpenPGP needs a GPG key id or fingerprint; SSH needs a key file path and gpg.format=ssh.
• Check that the key id in Settings matches a key the agent can actually use.
• A passphrase-protected GPG key needs a working gpg-agent. If the terminal can sign and the app cannot, the agent is usually the difference — unlock it in a terminal once.
• commit.gpgsign is read from the repository. The config viewer shows the effective value and where it came from.
• Turn off Sign commits in Settings to confirm signing is the cause.

CRLF and mixed line endings

A file with both CRLF and LF endings produces a diff where every line looks changed. Git’s core.autocrlf and .gitattributes decide how the file is checked out and staged, and the application follows those settings rather than overriding them.

• Set core.autocrlf or .gitattributes in the repository, not in the application.
• Use the diff’s ignore-whitespace toggle to review a change through the line-ending noise.
• If a formatter rewrites line endings while you are staging, the stage is rejected as stale. That is the stale guard doing its job: re-read the diff and stage again.

Long paths on Windows

Windows limits paths unless long path support is enabled. If clone or checkout fails on deep paths:

1. Enable long paths in Windows.
2. Set git config --system core.longpaths true.
3. Clone to a shorter root, for example C:\src\ instead of a deeply nested folder.

The application does not rewrite paths or silently shorten them.

Authentication failed

Push and pull authenticate through the system git, so the fix is almost always outside the application.

• SSH: unlock the key in a terminal (ssh-add), check the remote URL uses the right host and user, and confirm the key is loaded in the agent.
• HTTPS: the credential helper must have a usable token or password. Run the same command in a terminal once to let the helper prompt.
• Two-factor or SSO: tokens need the right scopes and may need authorisation for the organisation.

The application reports the authentication failure and does not ask for credentials itself.

Push blocked by the preflight

The push preflight refuses private key material outright and requires a typed confirmation for blocking findings. If the finding is a false positive:

• Inspect the reported path and line in the preflight list.
• Remove the file from the commits being pushed, or move the value to a secret store.
• Only confirm a blocking finding after reading it; the scan is a heuristic, not a guarantee.

Warnings — a large new file, a conflict marker, a suspicious string — need an explicit accept, not a typed phrase.

A file changed on disk while staging

That is the stale guard: the diff you saw no longer matches the file, so nothing is written to the index. Re-read the diff and stage again. If it repeats, something is still writing the file — a watcher, a formatter, a build, or a Git hook.

Still stuck

Collect the details before asking:

1. The error code and message from the notice.
2. The failing command from Git output.
3. The effective configuration from the config viewer.
4. The diagnostics ZIP from Settings → General → Export diagnostics.

See Diagnostics for what the ZIP contains. Read it before posting it publicly.