GitRoute Documentation
GitRoute is a fast, native desktop Git client. It runs natively on macOS, Windows, and Linux and gives you a clean, distraction-free interface to manage your repositories — without ever touching the terminal for everyday Git tasks.
fsnotify to detect external repo changes instantly.Installation
GitRoute ships as a single self-contained executable. Download the build for your platform from the Download page or build it from source.
System Requirements
- Git 2.28+ installed and available on your system
PATH - macOS 11+, Windows 10+, or Linux (X11/Wayland)
- ~60 MB disk space
macOS
- Download the
.dmgfrom the Download page. - Open the DMG and drag GitRoute.app to your Applications folder.
- On first launch, right-click → Open if Gatekeeper shows a warning.
GitRoute automatically extends PATH to include /opt/homebrew/bin and /usr/local/bin so Homebrew-installed Git and tools like git-lfs work without any manual shell configuration.
Windows
- Download the
.exeinstaller. - Run the installer and follow the prompts.
- GitRoute appears in your Start menu.
Linux
- Download the
.AppImageor.tar.gzarchive. - Make it executable:
chmod +x GitRoute.AppImage - Run:
./GitRoute.AppImage
First Launch
When you open GitRoute for the first time you'll land on the Workspace screen. The app remembers your last opened repository and restores it on subsequent launches.
Sign in (optional)
Open Profile in the sidebar and connect your GitHub account or SSO identity. This enables credential-free push/pull to private repositories.
Add your first repository
Click Open Repository and choose a local folder, or click Clone to clone a remote URL.
Explore the interface
The main window is divided into a sidebar (branches, stash, remotes) and the main panel which switches between the changed-files view, history, diff viewer, and more.
Opening a Repository
There are two ways to open a repository in GitRoute:
- Browse: Click Open Repository and select any folder containing a
.gitdirectory. - Recent repos: The Workspace shows your recently opened repositories in their groups for one-click access.
GitRoute remembers the last repository you had open and restores it on the next launch automatically.
Staging & Committing
The Changes panel shows every uncommitted file, split into Unstaged and Staged sections.
Staging files
- Click the
+icon next to any file to stage it. - Click Stage All to stage every changed file at once.
- Right-click a file for more options: stage, unstage, discard, stash, or add to
.gitignore.
Unstaging files
- Click the
−icon next to a staged file to move it back to unstaged. - Click Unstage All to clear the entire staging area.
Committing
- Stage at least one file.
- Type your commit message in the text area at the bottom of the Changes panel.
- Toggle Amend previous commit to fix the last commit message or add forgotten changes.
- Click Commit.
Keep the first line of your commit message under 50 characters as a short subject. Add a blank line followed by a longer body for context — GitRoute renders both clearly.
Discarding changes
Right-click any unstaged file → Discard Changes. For tracked files, GitRoute runs git restore --staged --worktree. For untracked files, discard permanently deletes the file — a confirmation dialog is shown first.
Adding to .gitignore
Right-click any file → Ignore File. GitRoute appends the path to your repository's .gitignore automatically.
Branch Management
The Branch Manager screen gives you full control over local and remote branches.
Switching branches
Click any branch in the sidebar or Branch Manager to check it out. GitRoute updates the UI immediately.
Creating a branch
- Click New Branch.
- Enter a branch name.
- Choose a base — any local branch, tag, or remote tracking branch.
- Optionally tick Switch to branch to check it out immediately.
- Click Create.
Checking out a remote branch
Click any remote-tracking branch (e.g. origin/feature/xyz). GitRoute automatically creates a local tracking branch and checks it out — equivalent to git checkout -b feature/xyz origin/feature/xyz.
Deleting a branch
Right-click a branch → Delete. Enable the force toggle to delete unmerged branches. Remote branches can also be deleted here (runs git push origin --delete <branch>).
Comparing branches
Select two branches in the Branch Manager and click Compare. GitRoute shows the commits unique to each branch and the full diff between them.
Diff Viewer
Click any file in the Changes panel to view its diff inline on the right. Double-click to open the standalone Diff Viewer window for a distraction-free full-screen view.
Reading the diff
- Lines prefixed with
+(green) are additions. - Lines prefixed with
−(red) are deletions. - Context lines are shown in grey.
Conflict diff
When a file has merge conflicts, the diff viewer automatically shows a Ours vs. Theirs side-by-side view using git diff :2:<file> :3:<file>.
GitRoute cancels any in-flight diff subprocess when you switch files — rapid clicking never stacks up background processes or shows stale results.
Commit History
The Changelog screen shows your full commit graph with hash, author, date, and subject on each row. The graph on the left visualises merges and parallel branches.
Viewing commit details
Double-click any commit to open the Commit Details window — a full-screen patch diff for every file changed in that commit.
Searching history
Use the Search screen to find commits by message, author, or date range.
Stash Management
The Stash Manager lets you save and restore work-in-progress changes without making a commit.
Creating a stash
- Stash All: Saves all staged and unstaged changes. Add an optional description message.
- Stash File: Right-click a file → Stash File to save only that file's changes.
- Stash Selected: Select multiple files, right-click → Stash Selected Files.
Restoring a stash
- Apply: Applies the stash but keeps it in the list.
- Pop: Applies the stash and removes it from the list.
- Drop: Deletes the stash entry without applying it.
Dropping a stash is permanent. The changes cannot be recovered after this action.
Cloning a Repository
From the Workspace screen, click Clone Repository.
Enter the remote URL
Paste an HTTPS or SSH URL (e.g. https://github.com/user/repo.git).
Choose destination
Click Browse to pick a local folder. GitRoute creates a new subfolder with the repo name inside it.
(Optional) Branch & SSH key
Specify a branch to clone and optionally point to a custom SSH private key for this repository.
Clone
Click Clone. GitRoute runs git clone and automatically opens the repo when done. If a custom SSH key was provided, it is saved to the repo's local git config for future operations.
Managing Remotes
The Remote Manager lists all configured remotes and lets you add, edit, or remove them.
Adding a remote
- Click Add Remote.
- Enter a name (conventionally
origin) and the URL. - Click Add.
Browsing a remote before cloning
Click List Remote Branches, paste a URL, and GitRoute fetches all available branches using git ls-remote --heads — without cloning the repository first.
Push, Pull & Fetch
Push
Click Push in the toolbar. If the branch has no upstream, GitRoute prompts you to select the remote and optionally set the tracking branch. Extra flags like --force-with-lease are available in the advanced options panel.
Pull
Click Pull to fetch and merge (or rebase, based on your git config) the upstream branch. If conflicts arise, GitRoute opens the Conflict Resolution window automatically.
Fetch
Click Fetch to download all remote changes without touching your working tree. Remote tracking branches update, and new remote branches appear in the Branch Manager.
Fetch regularly to keep remote-tracking branches up to date. This lets you preview incoming commits in the graph before deciding to merge or rebase.
SSH Keys
GitRoute supports per-repository custom SSH keys, overriding the system default key.
Setting a per-repository SSH key
- Open Remote Manager or the repository Settings.
- Click Select SSH Key. A native file picker opens, defaulting to
~/.ssh. - Pick your private key file. GitRoute saves the path to the repo's local git config.
All future git operations for that repository automatically use the selected key — no ssh-agent or GIT_SSH_COMMAND juggling needed.
Conflict Resolution
When a merge, pull, or rebase results in conflicts, GitRoute shows a Conflict badge on affected files and prompts you to open the Resolve Conflicts window.
3-Way merge editor
The conflict window shows three panes side by side:
- Ours — the current branch's version.
- Result — the editable merged output (center).
- Theirs — the incoming branch's version.
Edit the Result pane directly or use the arrow buttons to accept a block from either side. Click Save & Mark Resolved when done — GitRoute writes and stages the file automatically.
Closing the Resolve Conflicts window before saving will show a confirmation prompt. Unsaved resolution changes are lost if you dismiss without saving.
File Change History
Right-click any file → View Change History to open a dedicated window showing every commit that modified that file, in reverse chronological order. Click any commit to see the exact diff for that file at that point in history — equivalent to git log --follow -p -- <file>, but as an interactive timeline.
Repository Analytics
The Analytics screen provides a local, privacy-preserving view of your repository's activity. Metrics include:
- Total commits over time (bar chart)
- Top contributors ranked by commit count
- Most frequently changed files
- Branch activity timeline
All analytics are computed locally with git log — no data leaves your machine.
Workspace & Repository Groups
Organize all your repositories into named groups (e.g. Work, Open Source, Personal). Groups are stored in a local SQLite database.
Creating a group
- Click New Group in the Workspace sidebar.
- Enter a name and click Create.
Adding repositories to a group
- Open or clone a repository.
- Click Add to Group in the repository header and select the target group.
Reordering
Drag and drop groups and repositories within the Workspace to reorder them. The sort order is saved automatically.
Auto-sync per repository
Each repository entry has an optional Auto Sync toggle. When enabled, GitRoute periodically fetches from remotes in the background and displays an indicator when your local branch is behind upstream.
Built-in Terminal
The Terminal screen provides a command runner scoped to your current repository's root. It uses your system's default shell ($SHELL on Unix, COMSPEC on Windows).
Terminal commands inherit the same SSH key and proxy environment that GitRoute injects for GUI git operations, so commands you type here behave identically to clicking the GUI buttons.
The terminal is ideal for advanced operations not yet surfaced in the UI — such as git bisect, git rebase -i, or git filter-branch — while still benefiting from automatic UI refresh when those commands modify the repo.
Git Reset
In the Commit History, right-click any commit and choose Reset to this Commit. A dialog lets you pick the mode:
| Mode | Working Tree | Index | Use case |
|---|---|---|---|
--soft |
Unchanged | Unchanged | Undo commit, keep staged changes ready |
--mixed |
Unchanged | Reset | Undo commit + unstage, keep file edits |
--hard |
Reset | Reset | Completely discard all changes |
--hard reset permanently discards all uncommitted changes in your working tree. GitRoute shows a confirmation dialog before executing a hard reset.
GitHub Authentication
GitRoute supports two ways to authenticate with GitHub:
Device Flow (recommended)
- Go to Profile → Connect GitHub Account.
- GitRoute starts the OAuth Device Flow and displays a short user code.
- Open
https://github.com/login/devicein your browser, enter the code, and authorise GitRoute. - GitRoute polls automatically and stores the access token securely in the local SQLite database.
GIT_ASKPASS (HTTPS credential prompts)
For HTTPS operations, GitRoute installs a GIT_ASKPASS helper. When git needs a username or password it routes the prompt to GitRoute's native credential dialog — no terminal input required. The response is passed directly to the git subprocess.
If no credential is provided within 120 seconds, the askpass prompt times out and the git operation fails gracefully without hanging the UI.
SSO Login
GitRoute supports Single Sign-On via the Extendsware identity platform using PKCE.
Initiate SSO
Go to Profile → Sign in with SSO. GitRoute generates a PKCE code verifier/challenge pair and opens your browser to the authorization URL.
Authorize in browser
Log in with your SSO provider. After approval the identity server exchanges the code for an access token.
Auto-complete
GitRoute polls every 1.5 seconds (up to 5 minutes). Once the token is issued the app signs you in and fetches your profile automatically.
Git Configuration
GitRoute exposes your global git configuration through the Settings screen.
Common settings
user.nameanduser.email— shown on every commit you makecore.autocrlf— line-ending handlingpull.rebase— whether pull uses rebase or merge- Any other
--globalgit config key via the raw config editor
Per-repository config
Repository-scoped settings (custom SSH key, sync config) are stored in the repo's .git/config and in the GitRoute SQLite database, keeping them separate from your global identity.
App Settings
All GitRoute preferences are persisted locally in SQLite at:
- macOS:
~/Library/Application Support/GitRoute/gitroute.db - Windows:
%APPDATA%\GitRoute\gitroute.db - Linux:
~/.config/GitRoute/gitroute.db
Reset macOS permissions
If GitRoute loses access to system resources after an OS upgrade, go to Settings → Reset macOS Permissions. This runs tccutil reset All com.extendsware.gitroute in the background, after which you'll be re-prompted on the next sensitive operation.
Real-time Repository Sync
GitRoute uses fsnotify to watch specific files inside .git/. When another tool modifies the repository, GitRoute detects it and refreshes the UI automatically — no manual refresh button needed.
What triggers a refresh
.git/HEAD— branch switch or detached HEAD.git/COMMIT_EDITMSG— a new commit was made.git/ORIG_HEAD/MERGE_HEAD— reset or merge in progress.git/CHERRY_PICK_HEAD— cherry-pick in progress.git/packed-refs— fetch or push updated remote refs.git/refs/— local branch or tag updates.git/index— staging area changed
Changes are debounced by 500 ms — a burst of rapid events collapses into a single UI refresh to prevent flickering.
Index changes caused by git diff (which refreshes stat info silently) are filtered out while a diff is in progress, preventing false-positive reloads while you're browsing a file's diff.
Child Windows
GitRoute opens complex operations in dedicated child windows, keeping your main workspace uncluttered. Child windows close automatically when the parent app exits.
Full-screen patch diff for any commit. Double-click a row in the History screen.
3-way merge editor. Opens when you click a conflicted file.
Full-screen diff. Double-click a file in the Changes panel.
Per-file commit history. Right-click → View Change History.
All child windows inherit the same repository context and update in real-time when the repository changes.
Keyboard Shortcuts
| Action | macOS | Windows / Linux |
|---|---|---|
| Stage all files | ⌘ A | Ctrl A |
| Commit | ⌘ Enter | Ctrl Enter |
| Push | ⌘ P | Ctrl P |
| Pull | ⌘ L | Ctrl L |
| Fetch | ⌘ F | Ctrl F |
| Open repository | ⌘ O | Ctrl O |
| Open terminal | ⌘ T | Ctrl T |
FAQ
GitRoute says "git not found" on macOS
Install git via Homebrew: brew install git. GitRoute adds /opt/homebrew/bin to its PATH automatically. If git is installed elsewhere, symlink it: sudo ln -s $(which git) /usr/local/bin/git.
My SSH key isn't being used
Set the key explicitly for the repository via Remote Manager → Select SSH Key. GitRoute saves it in the repository's git config and uses it for all future operations on that repo.
The UI isn't refreshing after terminal changes
Make sure you're working inside the exact same directory that GitRoute has open. If you used a symlink or a different path, fsnotify may watch a different inode. Re-open the repository using the exact path shown in GitRoute's header.
How do I update GitRoute?
Download the latest version from the Download page and replace your existing installation. Follow GitHub releases for announcements.
Can I use GitRoute with GitLab or Bitbucket?
Yes. GitRoute works with any git remote — GitHub, GitLab, Bitbucket, Azure DevOps, or a self-hosted git server. GitHub OAuth is the only provider-specific integration; all other remotes use standard git over HTTPS or SSH.
Where is my data stored?
All GitRoute data is stored locally in SQLite. Nothing is sent to external servers except for SSO authentication and optional GitHub API calls when you're signed in.
Last updated: September 2026
Download