Getting Started

Installation

Download the latest .dmg from GitHub Releases
Open the .dmg file
Drag FinderGit to your Applications folder
Launch FinderGit from Applications or Spotlight

First launch on macOS

FinderGit is signed with Apple Developer ID and notarized by Apple, so Gatekeeper accepts it on first open. Just double-click — no right-click trick, no System Settings detour.

When you first launch any app downloaded from the internet, macOS shows a one-time confirmation dialog (""FinderGit” is an app downloaded from the Internet. Are you sure you want to open it?”). Click Open and you’re done — every subsequent launch is silent.

Before first launch (fresh Mac)

FinderGit uses the git binary that ships with the Xcode Command Line Tools. On a brand-new Mac you may need to install them and accept the Xcode license — otherwise every Git action inside FinderGit will surface a nonZeroExit(status: 89, …) error.

Install the Command Line Tools (skip if already installed):
```
xcode-select --install
```
A system prompt will appear — click Install and wait a few minutes.
Accept the Xcode license:
```
sudo xcodebuild -license
```
Scroll with Space, type agree, press Enter.

After these two steps, git works system-wide and FinderGit stops complaining.

Adding your first root folder

When you launch FinderGit for the first time, the sidebar is empty. You need to add at least one root folder — this is a directory that FinderGit will scan for Git repositories.

Click the + button in the toolbar, or go to File → Add Root Folder (⌘ ⇧ O)
Select a directory that contains your projects (e.g., ~/Projects or ~/Developer)
FinderGit will recursively scan for .git directories and display all found repositories

You can add multiple root folders. Each one appears in the sidebar and can be selected individually.

Understanding the interface

FinderGit has three main areas:

Sidebar (left)

Lists your root folders. Click one to show only its contents, or deselect to see everything.

You can drag roots to reorder them, type in the filter field at the top to narrow long lists, and group related projects together — Tower-style virtual containers that organise roots without touching anything on disk. See File Browser → Sidebar for the full breakdown.

File Browser (center)

An expandable tree view with sortable columns:

Name — file/directory name with system icon
Branch — current Git branch (for repositories)
Status — CLEAN, DIRTY, or an ahead/behind indicator (↑N, ↓N, ↑N ↓N) — see File Browser → Repository badges for all five states
Changes — number of modified files
Size — file size
Date Modified — last modification date

Click any column header to sort. Click again to reverse the order.

Detail Panel (right)

Shows details for the selected item:

Repository selected — branch info, action buttons (Fetch/Pull/Push), separate Staged and Unstaged changes lists with per-file Stage/Unstage, commit dialog
Sub-directory selected — filtered changes for that directory only
File selected — file info + inline diff (if modified)
Non-git file — basic file info (size, date, type)

Tips

Drop folders from the macOS Finder directly onto the sidebar to add them as roots
Right-click for context-sensitive actions (different for files, directories, and git repos)
Space bar on any selected file for Quick Look. .md and .markdown files open in a native renderer; other file types use the system Quick Look
Use ⌘ + / ⌘ − to zoom the tree view font size
Toggle Git Only above the file browser to hide non-repository files
Press ⌘ ? any time to open the live online docs in your browser