Porcelain

Porcelain is a lightweight native macOS Git client built with Swift and SwiftUI, with worktree mission control for repositories that have parallel work in flight. It is intended as a fast, calm alternative to GitHub Desktop for everyday Git work: open or clone repositories, review changes, stage files, commit, switch branches, inspect history, manage remotes, and sync with upstreams.

Porcelain is an MVP. It focuses on common workflows and on making multiple worktrees visible and reviewable from one window. Git operations are centralized through GitService, which runs the system git executable asynchronously.

Requirements

• macOS 26 or newer
• Xcode 26 or newer, or another Swift 6.2+ toolchain with the macOS 26 SDK
• Git available through the system path

Porcelain targets the SwiftUI glass effect APIs used by the current interface, and the package manifest declares macOS 26 as the deployment target.

Build

swift build

Run tests:

swift test

Run the app from SwiftPM:

swift run Porcelain

Create a local clickable app bundle:

./scripts/make_app_bundle.sh
open .build/Porcelain.app

You can also open the package in Xcode and run the Porcelain executable target.

Worktrees

The Worktrees tab shows every worktree attached to the current repository, including the current checkout, branch or detached state, dirty-file counts, staged/untracked/conflicted counts, insertions and deletions, tracking state, and the latest commit when available.

From the tab you can create worktrees, remove eligible worktrees, prune stale records, reveal or open a worktree in Terminal, and switch Porcelain to a different worktree. Dirty worktrees can be reviewed in place: Porcelain opens the same Changes workflow against that worktree path, so you can diff, stage, discard, commit, and then return to the list. This is meant for parallel branch work and for people running multiple Claude Code or Codex sessions in separate worktrees who want to review and land each one from a single window.

MVP Features

• First-launch empty state for opening, cloning, or initializing a repository
• Recent repository sidebar with search and local persistence
• Toolbar with current repository, branch picker, refresh, fetch, pull, push, and settings
• Changes view with staged, unstaged, untracked, renamed, deleted, binary, large, and conflicted file handling
• Worktrees tab with create, remove, prune, per-worktree summaries, context switching, and in-place review
• Unified and side-by-side diff rendering
• Stage, unstage, discard with confirmation, and commit with validation
• Branch list with checkout, create, rename, safe delete, merge, and ahead/behind state
• History view with commit metadata, changed files, diff, copy hash, and open-on-remote actions
• Remote add/edit/remove plus fetch, pull, push
• GitHub URL helpers for repository, branch, commit, compare, and pull request pages
• Optional GitHub token storage in Keychain
• Debounced repository file watching and async Git execution

Design Principles

• Native macOS UI and behavior
• No Electron, embedded web runtime, React Native, or large cross-platform framework
• Small dependency surface
• Git calls go through PorcelainCore/GitService.swift
• Credentials are stored only in Keychain
• Git work never blocks the main actor

Project Layout

Sources/
  Porcelain/       SwiftUI app, view models, AppKit integration
  PorcelainCore/   Git service, parsers, models, persistence, Keychain
Tests/
  PorcelainTests/       View-model concurrency and state-ordering tests
  PorcelainCoreTests/   Parser, Git-service, persistence, and file-watcher tests
Assets/            App icon and README images (regenerate with scripts/make_app_icon.sh)
docs/
  ARCHITECTURE.md
  FEATURE_STATUS.md

License

Porcelain is released under the MIT License.