Giovambattista Fazioli

Posted on Apr 15

FinderGit v0.1.0 — Stop Tabbing Between Finder and Your Git Client

#tooling #git #github #webdev

A day with twelve repositories

Before. You have a ~/Projects folder with twelve Git repos in it. To know which ones are dirty, you open Terminal, cd into each, run git status, repeat. Or you open Tower and wait for it to scan. Or you open VS Code twelve times. None of this is looking at your files — it's ceremony around looking at your files.

After. You open FinderGit and the folder tree looks like Finder's list view, plus four columns: branch name, clean/dirty/unpushed badge, number of changed files, and sizes and dates. Directories inside a dirty repo get a small orange dot with a count — so you spot modifications three levels deep without expanding anything.

That's the whole pitch. The rest of this post is the details.

What is FinderGit?

FinderGit is a native macOS app built with SwiftUI. It's positioned somewhere between Finder and a heavy Git client like Tower — it's not a replacement for either. If your day involves interactive rebases, submodule surgery, or cherry-picking across a long history, you'll still want Tower, GitX, or your CLI.

FinderGit is for the other 90% of the day: the part where you're browsing your projects, quickly checking "what did I leave dirty yesterday?", staging a few files, typing a commit message, pushing. Everything happens in the window that already shows your files — no context switch.

It runs on macOS 15 Sequoia or later. It's free, open-source (the website repo is public, the app repo will follow), and this is the public beta — v0.1.0. Expect a few rough edges; file them, I fix them.

✨ Key features

Tree view with sortable columns — Finder-style list view, but the columns are Name, Branch, Status, Changes, Size, Date Modified. Click any header to sort.
Live Git status per repository — a small badge next to each repo: CLEAN (green), DIRTY (orange), UNPUSHED (blue). Updates in real time via FSEvents.
Sub-directory dirty indicators — directories inside a repo show an orange dot with the number of modified files they contain. Walk down to the changes without expanding every folder.
Inline diff viewer — click any modified file and the right pane renders a unified diff with green/red lines, hunk headers, and line numbers. Supports HEAD, staged, unstaged, and even untracked files (rendered as all-added).
Git actions from the UI — Stage, Unstage, Commit, Push, Pull, Fetch. Per file or per repo. Commit messages get a TextField and two buttons: Commit Staged or Commit All & Push.
Native Markdown preview via Quick Look — press Space on any .md or .markdown file and it opens in a native renderer with a GitHub-style theme. Close with Space or Escape. Every other file type falls back to the system qlmanage, so you keep PDF, image, video previews for free.
Smart context menus — right-click adapts to what you clicked: repo gets Fetch / Pull / Push / Stage All; tracked file gets Stage / Unstage; non-git directory gets Add as Root Folder; everything gets Open / Reveal in Finder / Copy Path / Open in Terminal.
Multiple root folders — add as many as you want. Drop folders from Finder directly onto the sidebar; they become tree roots.
Search & filter — type in the toolbar to filter the tree by name (300ms debounce). Toggle Git Only to hide everything that isn't a repo — instant overview of just your projects.
Keyboard-driven — ⌘⇧F Fetch, ⌘⇧L Pull, ⌘⇧P Push, ⌘⇧A Stage All, ⌘⇧S Stage selected, Space Quick Look, ⌘+/⌘- zoom, ⌘⇧R Reveal in Finder. The usual Mac muscle memory.

🛠 What's powering it

For the developer-curious reader:

Swift + SwiftUI, deployment target macOS 15. The UI uses NavigationSplitView with a native Table(children:) for the tree, so sorting, keyboard navigation and selection come from AppKit under the hood.
Observation framework (@Observable) for state — no ObservableObject / @Published boilerplate. Structured concurrency (async/await) everywhere, no DispatchQueue.
FSEvents via a small GitWatcher that observes both the worktree and .git/HEAD, .git/index, .git/refs/, .git/FETCH_HEAD — debounced at the user-configurable latency. So pushing in Terminal updates the FinderGit badge within milliseconds.
git status --porcelain=v2 under the hood. /usr/bin/git is called via Process with a parser for the machine-readable output. No libgit2, no reimplementing history — the real git binary is the source of truth.
MarkdownUI for the Markdown preview. Pattern is extensible — same "interceptor" will take .css / .js / .swift with syntax highlighting in a future release.
Sparkle for auto-updates, EdDSA-signed. See below.
Personal Team signing, no Apple Developer Program ($99/year) required. That has implications for Gatekeeper — covered in the install section.

📦 Install

Requirements

macOS 15 (Sequoia) or later
Xcode Command Line Tools — FinderGit uses the system git binary, which on macOS is shipped as a stub. On a fresh Mac, run once:

  xcode-select --install
  sudo xcodebuild -license

Without these, every Git action inside FinderGit returns nonZeroExit(status: 89, …). This will be surfaced as a friendly dialog in a future release — for now, the Terminal workaround is a one-time setup.

Download

Grab the latest .dmg from the GitHub Release.
Open it and drag FinderGit into your Applications folder.

First launch — Gatekeeper

The app is signed with a free Personal Team, not with an Apple Developer ID. That means macOS Gatekeeper doesn't know it and will block the first launch with a generic warning. The fix is the standard Mac dance:

Open Applications in Finder.
Right-click on FinderGit.app → Open.
In the confirmation popup, click Open again.

Done once — from then on the app launches normally, including auto-updates. No paid developer program is funding this; you're trading a 5-second first-launch gesture for a free app.

🔄 Auto-updates

FinderGit ships with Sparkle. The app checks https://findergit.app/appcast.xml on launch and periodically; when a new version is available, you get the standard Sparkle alert with release notes. Each release DMG is signed with an EdDSA key — the public key ships inside the app, so Sparkle refuses to install an update it cannot verify. Even if my GitHub account were compromised tomorrow, an attacker couldn't push a malicious update without my private signing key.

You can also trigger a check manually via the FinderGit → Check for Updates… menu item.

🗺 What's next

The beta is functional, but plenty is already planned. Highlights of the public issue tracker:

Syntax highlighting in Quick Look for code files (.swift, .js, .ts, .py, .css, .json, …) — the Markdown interceptor pattern, extended.
Double-click a folder to navigate into it (drill-down, with a breadcrumb to go back).
Branch creation, renaming, deletion, checkout from the UI.
Stash management (save, pop, apply, drop).
GitHub / GitLab / Bitbucket providers — list Issues and Pull Requests for the current repo. Preference for gh / glab CLI when installed; REST fallback with a token in Keychain.
Kaleidoscope integration — jump from the inline diff to the full Kaleidoscope comparison, à la Tower.
diny integration for AI-generated commit messages, right next to the commit text field.
Auto-fetch on an interval wired to the setting that already exists.
Drag files from the tree to external apps — without breaking row selection, which is why it's not in v0.1.0.

If any of these are on your wish list, say so — priorities move.

Download, feedback, sponsorship

Three things, in order of how much they help:

Download it and try it → latest release. Ten minutes with real repos tells you more than any blog post.
Tell me what works and what doesn't → open an issue on the website repo. Bug reports, feature requests, workflow pain points — all welcome. Screenshots help.
If it turns into something you rely on, consider sponsoring → GitHub Sponsors. FinderGit is free, unsigned by Apple, and maintained in evenings and weekends. Sponsorship keeps the momentum.

DEV Community