Troubleshooting

Use this section when GitComet is not behaving as expected.

In this section:

• Crash Reports

For an unwanted merge, see Abort or Undo a Merge.

Before anything else

Check whether the problem is already fixed in a newer version: the changelog lists every release, and Download has the install instructions for each platform.

Git is missing or too old

GitComet requires Git 2.53 or newer. In Settings → Executables, check the version and path reported by the app. The desktop application's environment can differ from your terminal's environment. Older Git versions show an update notice and disable features that need newer Git, including repository maintenance.

Choose System PATH to use automatic discovery, or Custom executable to select Git explicitly. Browse to the executable, or enter its path and choose Use Path. If GitComet opens a Git-unavailable screen, use its Open Settings action to correct the path.

The Linux window does not open

Launch GitComet from an active Wayland or X11 desktop session. Under WSL, use WSLg. A Wayland-only session needs both WAYLAND_DISPLAY and XDG_RUNTIME_DIR; X11 needs DISPLAY.

If the main window fails to open, GitComet's error message lists each underlying cause; include all of it in a report.

If a manually installed binary reports a missing Fontconfig, XCB, XKB, Vulkan, EGL or Wayland library on Debian or Ubuntu, install the runtime libraries listed in the Linux installation guide. It includes the command and alternatives for systems that cannot run AppImages.

Windows graphics problems

GitComet switches to DirectX 11 on its own when DirectX 12 fails, at startup or while running, and keeps using it. To choose it yourself, open Settings → General → Graphics → Graphics renderer, choose DirectX 11 — compatibility and restart. To retry DirectX 12 after a driver update, choose Automatic and restart; a saved DirectX 11 fallback is not reset automatically. See Windows graphics renderer.

For a launch that fails before Settings opens, start GitComet from PowerShell with a temporary renderer override:

$env:GPUI_WINDOWS_RENDERER = "dx11"
gitcomet.exe

Use the full executable path if it is not on PATH. The override lasts for that shell session and does not change the saved renderer preference.

Repository maintenance recommendations

Settings → Maintenance controls Recommend repository maintenance. GitComet checks once a day whether Git recommends maintenance and offers to run it; it does not start maintenance automatically. Disable the setting to stop recommendations, or set maintenance.auto to false in a repository's Git config to skip that repository. This feature requires Git 2.53 or newer.

Fetch, pull, push, or clone fails

Check the remote URL and the authentication prompt. For SSH remotes, confirm that the matching public key is registered with your Git host and that the private key is available to your SSH setup. See SSH Keys.

Settings → Security / Privacy controls allowed Git transport protocols. GitComet can also ask you to trust a repository before running submodule operations. Review the prompt and the repository involved when an operation is blocked.

Abort merge is missing after merging the wrong branch

Abort merge appears beside MERGING while a merge is in progress. A merge that completes without conflicts, including a fast-forward, leaves nothing to abort. Right-click the commit your current branch pointed to before the merge and choose a reset mode, or create a new branch from that commit. See Abort or Undo a Merge before resetting, especially if you have local edits or already pushed the merge.

A merge result cannot be saved

The merge view blocks Save while the result still contains unresolved conflicts. Use Shift+F2 / Shift+F3 to find the remaining conflicts, choose the intended inputs or edit the output, then save. In a repository, Save & stage also marks the file resolved in Git. See interactive conflict resolution.

Commit signature badges are missing

First enable Settings → Git log → Verify commit signatures; it is off by default. Until then, Executables shows GPG and ssh-keygen as Not checked. Check the verifier under Executables and make sure your local Git configuration has the signer's public key. See Commit signature badges for status meanings and refreshing cached results.

Difftastic shows a line diff

When Difftastic cannot compare a file, the viewer falls back to the line engine and shows the reason. Causes include an unsupported language, a parse error, a source over 1 MB and a comparison that takes longer than five seconds. Your Difftastic preference stays selected for other files. See Syntax-aware diffs with Difftastic.

A custom theme does not appear

Place the .json bundle in the user themes directory, declare "schema_version": 2, and give it a filename and theme key that do not collide with a built-in theme. Settings → Appearance lists skipped files and themes with their path and reason. The expanded built-in collection reserves filenames such as github.json, nord.json, catppuccin.json and eldritch.json; rename a conflicting custom file and give its themes unique keys. See theme validation.

Report a reproducible problem

Include your GitComet version, operating system, Git version, installation method, exact error, and steps to reproduce in a GitHub issue. For an unexpected exit, use the crash report and log files.