GitRoute Logo GitRoute
v1.0

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.

⚡
Native Performance
Compiled Go binary with a webview UI. No Electron overhead.
🔄
Real-time Sync
Uses fsnotify to detect external repo changes instantly.
🔐
Secure Auth
Native GIT_ASKPASS, SSH keys, GitHub OAuth & SSO.
🗂️
Workspace Groups
Organize all your repos in named groups, stored locally in SQLite.

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

  1. Download the .dmg from the Download page.
  2. Open the DMG and drag GitRoute.app to your Applications folder.
  3. On first launch, right-click → Open if Gatekeeper shows a warning.
Note

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

  1. Download the .exe installer.
  2. Run the installer and follow the prompts.
  3. GitRoute appears in your Start menu.

Linux

  1. Download the .AppImage or .tar.gz archive.
  2. Make it executable: chmod +x GitRoute.AppImage
  3. 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.

1

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.

2

Add your first repository

Click Open Repository and choose a local folder, or click Clone to clone a remote URL.

3

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 .git directory.
  • 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

  1. Stage at least one file.
  2. Type your commit message in the text area at the bottom of the Changes panel.
  3. Toggle Amend previous commit to fix the last commit message or add forgotten changes.
  4. Click Commit.
Tip

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

  1. Click New Branch.
  2. Enter a branch name.
  3. Choose a base — any local branch, tag, or remote tracking branch.
  4. Optionally tick Switch to branch to check it out immediately.
  5. 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>.

Note

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.
Warning

Dropping a stash is permanent. The changes cannot be recovered after this action.

Cloning a Repository

From the Workspace screen, click Clone Repository.

1

Enter the remote URL

Paste an HTTPS or SSH URL (e.g. https://github.com/user/repo.git).

2

Choose destination

Click Browse to pick a local folder. GitRoute creates a new subfolder with the repo name inside it.

3

(Optional) Branch & SSH key

Specify a branch to clone and optionally point to a custom SSH private key for this repository.

4

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

  1. Click Add Remote.
  2. Enter a name (conventionally origin) and the URL.
  3. 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.

Tip

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

  1. Open Remote Manager or the repository Settings.
  2. Click Select SSH Key. A native file picker opens, defaulting to ~/.ssh.
  3. 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.

Warning

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

  1. Click New Group in the Workspace sidebar.
  2. Enter a name and click Create.

Adding repositories to a group

  1. Open or clone a repository.
  2. 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).

Note

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
Warning

--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)

  1. Go to Profile → Connect GitHub Account.
  2. GitRoute starts the OAuth Device Flow and displays a short user code.
  3. Open https://github.com/login/device in your browser, enter the code, and authorise GitRoute.
  4. 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.

Note

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.

1

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.

2

Authorize in browser

Log in with your SSO provider. After approval the identity server exchanges the code for an access token.

3

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.name and user.email — shown on every commit you make
  • core.autocrlf — line-ending handling
  • pull.rebase — whether pull uses rebase or merge
  • Any other --global git 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.

Tip

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.

Commit Details

Full-screen patch diff for any commit. Double-click a row in the History screen.

Resolve Conflicts

3-way merge editor. Opens when you click a conflicted file.

Diff Viewer

Full-screen diff. Double-click a file in the Changes panel.

Change History

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⌘ ACtrl A
Commit⌘ EnterCtrl Enter
Push⌘ PCtrl P
Pull⌘ LCtrl L
Fetch⌘ FCtrl F
Open repository⌘ OCtrl O
Open terminal⌘ TCtrl 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