A Linux desktop Git client built with Rust, Tauri 2, and TypeScript. The interface
uses a Linear-inspired dark canvas, neutral lifted surfaces, restrained lavender
controls, and Geist fonts bundled offline. A persistent sidebar lists local and
remote branches and tags beside the full-height, scrollable commit graph. Select
a sidebar entry to filter history, or All branches to see their connections.
The graph keeps inline ref labels and opens commit details on demand. Visual
conventions live in DESIGN.md.
Open, init, or clone a repository, browse branches and merge parents, inspect commit or working-tree diffs (unified or side by side, with changed words marked), stage/unstage whole files or single hunks, discard edits, stash work, create or amend commits, create, switch, rename, and delete branches, check out remote branches, merge, revert, cherry-pick, tag, reset, and clean up (rebase) commits, browse file history and blame, open pull requests, resolve conflicts block by block, free space taken by ignored build output and caches, keep several repositories open as tabs, and fetch/pull/push. Remotes are fetched quietly every five minutes, and GitGUI checks GitHub once a day for a newer published release.
Install the latest release on Linux (x86-64) or macOS (Apple silicon or Intel):
curl -fsSL https://raw.githubusercontent.com/MDHaarith/GitGUI/GitGUI/scripts/get.sh | shOn 64-bit Windows, run in PowerShell:
& ([scriptblock]::Create((Invoke-WebRequest -UseBasicParsing https://raw.githubusercontent.com/MDHaarith/GitGUI/GitGUI/scripts/get.ps1).Content))Both scripts download the latest release and verify its asset against
SHA256SUMS.txt before installing; missing or mismatched checksums stop the
installation. Linux uses ~/Applications/GitGUI/<version>/AppDir, the current
symlink and a desktop launcher, keeping the AppImage and checksum beside it.
macOS copies the app from the universal DMG to /Applications (requesting sudo
if needed); Windows runs the NSIS installer silently. Git must already be on PATH.
To build and install from source instead:
npm install
npm run install:appThe installer detects the operating system, builds GitGUI, removes every older installed version, and installs the new one:
- Linux:
~/Applications/GitGUI/<version>, acurrentsymlink, and agitgui.desktoplauncher. AppImageLauncher copies of GitGUI and their launchers are removed too. A running GitGUI keeps the old version until you close it. - macOS:
/Applications/GitGUI.app. - Windows (Git Bash): runs the NSIS installer silently.
Or download an installer from the
releases page: an AppImage, RPM,
.deb or portable .tar.gz for Linux, a universal .dmg (Apple silicon and Intel)
for macOS, and a -setup.exe for Windows. GitGUI needs Git installed and on PATH
(Git for Windows on Windows; on macOS the
Xcode command line tools or Homebrew Git).
The portable archive contains gitgui and license files; extract it and run
./gitgui. It requires the system WebKitGTK 4.1/GTK 3 libraries as well as Git.
Linux packages built on Fedora may require a newer glibc than older distributions
provide. SHA256SUMS.txt covers all uploaded release assets except itself;
checksums for macOS, Windows and the VSIX appear when cross-platform CI finishes.
Homebrew, winget and marketplace submission instructions are in
packaging/README.md.
The macOS and Windows builds are not signed with a paid certificate yet:
- macOS: the first time, right-click GitGUI in Applications and choose
Open, or run
xattr -dr com.apple.quarantine /Applications/GitGUI.app. - Windows: if SmartScreen warns, choose More info, then Run anyway.
vscode-extension/ adds GitGUI: Open Repository in GitGUI to VS Code, with a
button in the Source Control title bar and an Explorer folder menu entry. Download
gitgui-<version>.vsix from the releases page (or run npm run package in
vscode-extension/) and install it with
code --install-extension gitgui-<version>.vsix. It launches the installed
desktop app; see vscode-extension/README.md.
./src-tauri/target/release/gitgui
# Or open a repository immediately:
./src-tauri/target/release/gitgui /absolute/path/to/repositoryThe Fedora x86-64 installer is generated at
src-tauri/target/release/bundle/rpm/GitGUI-0.2.0-1.x86_64.rpm.
Install it with your package manager, then launch GitGUI from the application menu.
The x86-64 AppImage is generated at
src-tauri/target/release/bundle/appimage/GitGUI_0.2.0_amd64.AppImage.
Run it without installing:
chmod +x src-tauri/target/release/bundle/appimage/GitGUI_0.2.0_amd64.AppImage
./src-tauri/target/release/bundle/appimage/GitGUI_0.2.0_amd64.AppImageThe AppImage requires system Git 2.43+ and FUSE support. If FUSE is unavailable,
run it with APPIMAGE_EXTRACT_AND_RUN=1. This build uses Fedora 44 (glibc 2.43);
compatibility with older distributions is unverified. Build on the oldest target
distribution before distributing a broadly compatible Linux release.
The desktop installation uses ~/Applications/GitGUI/0.2.0, with a stable
~/Applications/GitGUI/current symlink and one gitgui.desktop launcher. The
launcher runs the extracted AppRun directly, which prevents AppImageLauncher
from creating duplicate installations. The versioned AppImage and its SHA-256
checksum are kept beside the extracted application. The toolbar displays the
native application version. Repository data and saved drafts use the existing
com.gitgui.app application profile.
Init repository creates a repository with safeguards enabled; Enable
safeguards in Changes adds them to an existing one. The hooks block staged .env
files and lines that look like API or private keys, and run the test command in
git config gitgui.testCommand (set to npm test or cargo test when detected)
before code commits. GitGUI installs pre-commit and
post-commit hooks and adds VERSION, CHANGELOG.md, and an AGENTS.md section
where missing. Commits that change code (anything but Markdown, docs/, and tests)
must bump the version in package.json, Cargo.toml, or VERSION and add a
changelog entry; each new version is tagged v<version>. The commit form's version
selector does the bump, lockfile sync, and changelog entry for you, so command-line
agents and GitGUI follow the same rule.
Checkpoints save a snapshot of every file, including new ones, without
committing or touching what you staged. GitGUI also saves one when you come back to
the window (at most every 10 minutes, only when files changed) and keeps the latest
100 under refs/gitgui/checkpoints. Restoring one saves the current files first and
keeps files created afterwards. A hint bar and error messages explain conflicts,
detached HEAD, and sync problems in plain English.
Review AI changes lists every file changed since your last saved checkpoint (or the last commit), riskiest first: possible secrets, removed tests, deletions, dependency and config changes, and large edits. Undo one file or all of them; a checkpoint is saved first. Health warnings in the hint bar flag files over 800 lines, deleted tests, new npm dependencies, three or more new TODOs, commits left unpushed for a day, and code that exists only on this computer.
Claude explains staged changes, the AI session, or a conflicted file, and
Write message with AI drafts the commit message. Requests go to
claude-opus-5-5 through curl with server-side fallback enabled
(fallbacks: "default"); the key comes from ANTHROPIC_API_KEY, the key saved in
the OS credential store, or ant auth. Existing private key files migrate on first read;
settings report when no credential store is available and a private file is used.
Changes over about 100k tokens are refused rather than cut. The dialog shows each
answer's tokens and cost and a running total.
Assistant opens a repository chat alongside Git. Read-only tools inspect status, working or commit diffs, recent history, files at a commit, and branches. Commits permission adds staging and committing; Everything adds branch creation, switching, and stashing. Every write needs an Allow click and saves a checkpoint. Calls and results stay visible in the chat; Enter sends, Shift+Enter adds a line, and answers can be copied as Markdown. HTTP requests run outside the Git lock. Command-line agents provide plain chat without GitGUI tools.
AI settings switches the provider: Gemini, DeepSeek, OpenAI, OpenRouter, Groq,
Mistral, xAI, Ollama, LM Studio, or any OpenAI-compatible /chat/completions API (address, model, key), or a
command-line agent such as codex exec -, claude -p, or opencode run that reads
the request on stdin. Agents run in an empty temporary folder for up to 10 minutes,
with GitGUI's repository tools unavailable. These are user-configured programs,
not an OS sandbox. Settings live in
~/.config/com.gitgui.app/ai-provider.json without API keys; keys use Secret Service
on Linux, Keychain on macOS, or Credential Manager on Windows. A private file is
used only when the credential service is unavailable; a locked store must be
unlocked. Only Claude answers are priced.
Try something risky starts a try/<name> branch; Keep it merges it back
with a merge commit, Throw it away deletes it after saving a checkpoint.
Publish (shown instead of Fetch, Pull, and Push until a remote exists) creates a private GitHub repository with gh or adds an existing empty repository URL, then pushes the main branch you choose first, so it becomes GitHub's default, followed by the current branch. Conflicted files appear in a dashboard with Accept Yours, Accept Theirs, and
Merge… for a three-pane editor. Edit Result, accept either side or both per block,
or Ignore to keep the base; Apply non-conflicting changes and Resolve simple
handle changes Git can combine safely. Saving marks the file resolved. During a
rebase, Yours means your commit being replayed. Continue and Abort are labeled for
the merge, rebase, cherry-pick, or revert; Skip is available except for merges.
Checkpoints protect files before resolutions, Skip, and Abort. Undo last
commit moves an unpushed commit's changes back to Staged and deletes its version
tag. AI rules edits AGENTS.md (with starter rules) and links it from
CLAUDE.md. Run starts git config gitgui.runCommand, else npm run dev/
start, cargo run, or a Python entry point, streams its output, and explains
common crashes. Help shows the tour and a glossary; button tooltips explain
Git terms.
The app remembers the last selected repository, offers the eight most recently opened repositories, and keeps commit drafts locally for each repository. Git remains responsible for credential helpers, SSH agents, hooks, and signing. Missing identity/authentication/signing setup produces Git's error message and keeps the draft. Only open repositories whose local configuration you trust.
Search loaded commit subjects, authors, and hashes with Ctrl+F. Enter moves to the next match; Shift+Enter moves back. Search preserves the full graph and marks matches. Load more history or choose a branch scope to search older commits.
Named branch tips start separate colored graph paths, including a branch that is only ahead of another branch. Local and remote labels at the same commit share a path; tags do not create additional lanes. Lines always follow actual parents.
Ctrl/Cmd-click adds or removes commits from the graph selection; Shift-click selects a range. Commit actions copies selected SHAs, cherry-picks or reverts commits in ancestry order, or opens a squash/drop plan for review. With two selected, Compare two commits opens their diff. In Details, choose a file and Open full width.
Clean up from here adds older commits to the rebase plan. Edit files (stop here) pauses at that commit: change files, stage them, Amend paused commit in Changes, then Continue. The footer shows the resulting commit count. Reword commit can change any current-branch commit message, including root and merge commits, while preserving files and merge resolutions. History changes save a Restore history checkpoint and participate in Undo. Restoring history requires a clean branch.
Open Details to review commits alongside the graph. The pane follows commit selection and can be resized horizontally. Diffs show old/new line numbers; Alt+Up/Down moves between changed files. Working diffs reload on refresh, including when the app regains focus, and clear when the selected change is gone.
Fetch, pull, and push display elapsed time and Git's live progress when available. Messages are bounded and credential-redacted. Disabled action buttons explain their requirements in tooltips and accessibility descriptions.
Requirements: Rust 1.88+, Node 20.19+/22.12+ (tested with Node 24), and Git 2.43+.
Linux also needs the GTK 3 and WebKitGTK 4.1 development libraries; macOS needs the
Xcode command line tools; Windows needs the Visual Studio C++ build tools and
WebView2 (included in Windows 10 and 11). Developed on Fedora 44 x86-64; CI tests
every push on Ubuntu, macOS, and Windows (.github/workflows/cross-platform.yml).
npm ci --ignore-scripts
npm run tauri dev
npm run tauri buildThe release build produces both AppImage and RPM packages. To package an existing release binary as an AppImage without recompiling:
npm run tauri -- bundle --bundles appimageThe npm dependencies have no install lifecycle scripts. The committed lockfiles
pin the installed dependency graph. Fonts and their OFL licenses are in
src/assets/fonts; no Google Fonts request is made by the desktop app.
gitgui-mcp exposes GitGUI's Git backend over stdio without starting the desktop
app. Build it with cargo build --manifest-path src-tauri/Cargo.toml --bin gitgui-mcp --release, or use the binary shipped with the app. Regular tauri build builds
and bundles both Cargo binaries; default-run keeps gitgui as the desktop entry
point. No separately copied bundle.externalBin sidecar is needed
(Tauri's binary discovery).
Packaged Linux installs put it beside gitgui (inside an extracted AppImage:
usr/bin/gitgui-mcp); macOS: GitGUI.app/Contents/MacOS/gitgui-mcp; Windows:
gitgui-mcp.exe in the installation folder. Use its absolute path in client
configuration, or put it on PATH.
The default repository is --repo <path> or the current directory. Every tool
also accepts an optional repo override. Only use repositories whose Git config
and hooks you trust. Git must be installed, just as for the desktop app.
Read tools are always available: status, log (limit, branch and literal path),
show_commit, diff (working, staged, or two refs), branches, tags, stashes,
blame, file_history, list_checkpoints, and code_search. Code search needs
code-review-graph installed and an index built with
code-review-graph build --repo /absolute/path/to/repo.
Permissions are read once at server startup and default to read-only:
GITGUI_MCP_ALLOW_WRITE=1addsstage,unstage,commit,create_branch,switch_branch,stash_save, andsave_checkpoint.- Independently,
GITGUI_MCP_ALLOW_DESTRUCTIVE=1addsdiscard_files,reset,restore_checkpoint, anddrop_stash. These save a checkpoint before changing work; unchanged snapshots are deduplicated, as in the desktop app. Dropped stashes also retain their full contents at the returnedrecoveryRef, recoverable withgit stash apply <recoveryRef>(including untracked files).
Disabled tools are hidden and calls to them are refused. Stage, unstage, and
discard take the file IDs returned by status; drop_stash takes the index and
message returned by stashes. Checkpoints exclude ignored files. Tool content is
credential-redacted and capped at 64 KiB with a truncation notice; narrow limit,
path, or the blame line range for larger results. Requests are limited to 1 MiB.
The server implements newline-delimited JSON-RPC 2.0 initialization, ping, and
tool discovery/calls, with tool failures returned as isError: true text results.
Claude Desktop — add to claude_desktop_config.json (replace both absolute
paths; use escaped backslashes or forward slashes on Windows):
{
"mcpServers": {
"gitgui": {
"command": "/absolute/path/to/gitgui-mcp",
"args": ["--repo", "/absolute/path/to/repo"]
}
}
}Claude Code — with gitgui-mcp on PATH, run from your repository:
claude mcp add gitgui -- gitgui-mcp --repo .Cursor — put the same mcpServers JSON shown above in .cursor/mcp.json
(project) or ~/.cursor/mcp.json (user).
VS Code — put this in .vscode/mcp.json:
{
"servers": {
"gitgui": {
"type": "stdio",
"command": "/absolute/path/to/gitgui-mcp",
"args": ["--repo", "${workspaceFolder}"]
}
}
}To opt into writes, add "env": { "GITGUI_MCP_ALLOW_WRITE": "1" } alongside
command and args in any of these JSON entries, then restart the server.
npm run version:check
npm test
npm run test:ui # real UI in headless Chromium against a mocked Tauri bridge
npm run build
cargo test --manifest-path src-tauri/Cargo.toml
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets -- -D warnings
cargo fmt --manifest-path src-tauri/Cargo.toml -p gitgui --check
npm audit
cargo audit --file src-tauri/Cargo.lockReal-repository tests use disposable fixtures and a local bare remote. They cover partial staging, unborn HEAD, filenames with spaces/newlines/non-UTF-8 bytes, renames, failed hooks, merge parents, frozen history pages, tags, detached HEAD, linked worktrees, binary/symlink previews, safe branch switches, mirror-config protection, fast-forward pull, rejected pushes, and shallow history.
The native desktop smoke test drives the actual release binary and Rust bridge using Tauri's native WebDriver workflow. It checks the branch sidebar, graph filtering, keyboard focus, fonts, on-demand details, selective staging, commits, retained drafts after failed hooks, branch actions, publishing, and fetch.
With tauri-driver and WebKitWebDriver installed:
GDK_BACKEND=x11 WEBKIT_DISABLE_DMABUF_RENDERER=1 tauri-driver
python3 scripts/desktop_smoke.py src-tauri/target/release/gitguiRun the driver on an isolated test desktop/data profile if testing alongside normal
app use. The script creates and deletes only its own temporary repository. Its
rendered app DOM is saved to test-results/desktop.html. WebKit's screenshot
endpoint can stall on some Linux graphics setups, so it is not part of the workflow assertions.
package.json is the version source. Tauri reads it directly; the npm version
hook synchronizes the Rust manifest and lockfile. Builds reject mismatched
versions. Every commit that changes app code gets its own version (Semantic
Versioning: patch for fixes, minor for features, major for breaking changes) and
a CHANGELOG.md entry. npm install enables .githooks: pre-commit rejects
app changes without a bump and changelog entry; post-commit tags v<version>.
npm version minor --no-git-tag-version
# add "## <version> — <date>" to CHANGELOG.md
git add -A && git commit
npm run tauri -- build --bundles appimageMerge the release into the existing GitGUI branch. Keep versioned release
filenames and checksums; point the desktop's current symlink at the new extracted release after verifying
startup. Retire obsolete launchers and binaries without deleting application
profiles or repository files.
When building inside an AppImage-based IDE, clear its inherited launcher variables for the build command:
env -u APPIMAGE -u APPDIR -u ARGV0 -u OWD -u ELECTRON_RUN_AS_NODE \
-u REDIRECT_APPIMAGE -u TARGET_APPIMAGE -u APPIMAGE_SILENT_INSTALL \
-u LD_LIBRARY_PATH npm run tauri -- build --bundles appimage- One active repository. History loads in 200-commit pages, up to 10,000 commits per scope. Unloaded parents remain visible as continuation paths.
- Metadata/index reads are limited to 16 MiB. Diff/file previews are limited to 2 MiB and 5,000 rendered lines, with an explicit truncation notice.
- Pull defaults to fast-forward only. A diverged pull offers Merge or Rebase for that pull without changing Git config; blocked pulls and branch switches offer Stash & retry. A conflicting pull or stash pop keeps the stash for recovery.
- Push sends only the current branch. A non-fast-forward rejection offers an explicitly confirmed force push with a lease on the observed remote commit; Git refuses if that branch changes. Push never mirrors other refs.
- Branch menus can fetch or fast-forward a branch without checking it out, or reset it to the same-named remote branch after confirmation and a checkpoint. Checked-out branches must be updated from their own worktree. Compare branches in Tools to see commits unique to each side and the common-ancestor-to-B diff.
- Tools → Worktrees lists, adds and removes linked worktrees and opens them as repository tabs. Close a worktree's tab before removing it. Dirty removal saves a checkpoint and a stash including ignored files; locked worktrees are refused. Branches show their last author, relative date and a stale badge after 90 days.
- The merge editor reads index stages 1, 2, and 3 for regular UTF-8 text files within 2 MiB and 5,000 lines per version. Binary, larger, and symbolic-link conflicts can use whole-file Accept Yours / Accept Theirs.
- Staging works per file, per hunk, or selected changed lines (click or Shift-click). History search covers up to 10,000 loaded commits. Amend and undo refuse commits that were already pushed.
- Squash, drop, and interactive cleanup require a linear commit range. Standalone reword preserves merge topology. Rewrites refuse published commits by default; opting in warns that the next push needs a confirmed force push with lease. Rewritten commit signatures are removed.
- The update check only sees published releases, not drafts.
- Nested submodule operations are outside this release.
- "Install and restart" replaces the Linux AppImage in place; on macOS and Windows, Download opens the release page with the new installer.
Tauri's GTK 3 stack uses glib 0.18.5. A local override in vendor/glib backports
the upstream mutable out-pointer fix for
RUSTSEC-2024-0429.
Its regression test is also run in an optimized build. The audit exception is
limited to that fixed advisory; the original source and licenses are preserved.
The dependency audit still reports the build-time, unmaintained proc-macro-error advisory through the GTK tooling. It has no patched upstream version. Track it when upgrading the Tauri/GTK dependency stack; no audit finding is silently suppressed.