English | 简体中文
A native Git client for macOS that works with repositories on your Mac and on your servers.
Note
Spooky is still in development and hasn't been released yet. Its features and interface may still change.
Spooky opens Git repositories on your Mac, and works directly with repositories on another machine over SSH.
A server repository's working tree stays on the server: Git runs there and files are read and written over SFTP, so the repository never has to be cloned to your Mac.
Connections use the system's SSH and the host aliases in ~/.ssh/config. OpenSSH handles authentication, host keys, and connection sharing.
This README is for developers. It covers the tools you need, how to build, run, test, and debug Spooky, and how to contribute.
-
macOS 26 or later
-
Xcode with Swift 6.2 or later. CI and releases build with the Xcode set by
DEVELOPER_DIRinci.yml; use the same version to get the same results -
mise, which runs the build, test, code style, release, and website tasks defined in
mise.toml
Spooky runs Git on the machine where each repository is, so the machines you test with need:
-
Git
2.41.0or later on your Mac and on servers, as Spooky usesgit fetch --porcelain- Local repositories use
/usr/bin/gitunless another Git program is chosen in Settings - Server repositories use the Git on that host
- Local repositories use
-
On servers:
- OpenSSH with reverse Unix socket forwarding
- OpenSSH
8.4or later, to enter SSH private key passphrases for Git on the server MaxSessionsof 10 or more in the sshd configuration (the OpenSSH default)/usr/bin/perlwith the core modulesIO::Socket::UNIX,JSON::PP, andPOSIX- No root access or background services
-
Git LFS
2.9.0or later for repositories that use it, on the machine where the repository is and in thePATHthat Git uses there -
sshfs with macFUSE or FUSE-T on your Mac, to mount server repositories with sshfs
-
An account on github.com, GitLab.com, or a self-managed GitLab
9.0or later, for pull requests and merge requests
Run commands from the repository root:
# Get the source code
git clone https://github.com/rakuyoMo/Spooky.git
cd Spooky
# Build the core library and the app
mise run build
# Launch the app
swift run Spookyswift run starts the bare executable, without the app icons, release notes, licenses, and localized permission prompts that come with an app bundle. Updates and system notifications are turned off as well.
Build a development app when you need any of these, or when you want to open Spooky from the Finder or set its language separately in System Settings:
# Build .build/Spooky.app
./scripts/build-app.sh
# Launch the built app
open .build/Spooky.appThe release app uses a release build and is ad-hoc signed and verified:
# Build build/Spooky.app
mise run bundleSpooky is a Swift package with two main targets, each organized into folders by feature:
-
SpookyKit, inSources/SpookyKit/: the core library. It runs Git on your Mac or on a server, reads and writes repository files, and parses Git's output -
Spooky, inSources/Spooky/: the app. AppKit manages its windows, split views, toolbars, and menus, and SwiftUI provides the content
A few designs run through the whole codebase:
-
One way to run Git: every Git call goes through
GitRunner, which works the same way for local and server repositories. Local repositories run the Git program chosen in Settings, and server repositories run Git on the server through/usr/bin/ssh -
One write at a time: each repository has one write queue shared by all its windows. Writes run one at a time in the order they were started, and a write started while another is running waits its turn. Read-only Git commands are registered in
RepositoryOperationQueue.isReadOnly, and every other command is treated as a write -
Server connections: each server working tree gets its own SSH master connection (ControlMaster), which exits after 10 idle minutes. After the first connection check, the Perl helper
spooky-remote.plis installed in~/.spooky/bin/on the server, named after a digest of its contents, to manage remote processes and callbacks. Files are read and written over SFTP on the same master connection -
Callbacks: when Git asks for a password, a passphrase, or an editor,
CallbackRelaybrings the request back to the Mac, through a reverse Unix socket for server repositories and a private Unix socket for local ones -
Refreshing: local repositories refresh when FSEvents reports a change. Server repositories are polled every 2 seconds in the foreground and every 10 seconds in the background
-
Files for other apps: Quick Look, external tools, and dragged-out files get their files through
RepositoryFileCache, so server paths never reach local file APIs -
Hosting services: requests to GitHub and GitLab are made from the Mac through
HostingClient
Architecture describes what each folder is for and the designs that span modules, and AGENTS.md lists the rules that code must follow. Both are in Chinese.
# Run the tests that are on by default
mise run test
# Run a single suite
swift test --filter LocalizationTests-
Tests use Swift Testing. Tests that use Git run in temporary repositories and ignore the system and user Git configuration
-
App tests make their windows transparent and turn off sheet animations, so nothing shows up on screen while they run
-
Tests that read windows through the Accessibility API only run when the process running them has Accessibility access. In a terminal, that's the terminal app
-
Git LFS tests only run when
git-lfsis inPATHor in Homebrew's folders -
Tests have no time limits. If a run seems stuck, the test that started but never finished is the stuck one; CI stops the test job after 30 minutes
Tests that need a server, github.com, or a large repository are skipped unless you turn them on:
| Variable | Turns on |
|---|---|
SPOOKY_REMOTE_TESTS=1 |
Server tests, run against the SSH host alias spooky-test |
SPOOKY_GITHUB_TESTS=1 |
Pull request tests on a github.com test repository, together with SPOOKY_GITHUB_TOKEN and SPOOKY_GITHUB_REPOSITORY |
SPOOKY_PERFORMANCE_TESTS=1 |
Performance tests on a generated repository with 100,000 files and 60,000 commits |
Testing (in Chinese) explains how to set them up, and has manual acceptance steps for each milestone.
Spooky logs under the com.rakuyo.spooky subsystem, with each type as its own category:
# Stream the logs live
/usr/bin/log stream --predicate 'subsystem == "com.rakuyo.spooky"' --level info
# Show the logs from the last 5 minutes
/usr/bin/log show --last 5m --predicate 'subsystem == "com.rakuyo.spooky"' --infoThe logs record connection state changes, remote sessions, failed and cancelled Git commands, writes, and callback requests. They never contain command arguments or output, commit messages, or credentials.
Repository paths, host aliases, and other user data are marked private, so the logs show them as <private>. In zsh, log is a built-in command, so use the full path.
Turn on Show Developer menu in Settings › General to add the Developer menu:
-
User Defaults: log all preferences to standard output, reset settings while keeping bookmarks, user profiles, accounts, and the locations of server repositories on this Mac, or clear the whole preferences domain without asking
-
Test Crash Reporting: crash with a fake exception or a bad access, to test crash reports
-
Auto-Archive Branches: run auto-archive now, or reset the times each repository was last checked
-
Show What’s New Card: show the What’s New card in the sidebar again
-
Auto-Reload Repository: turn refreshing on file changes and polling on or off
On your Mac:
| Data | Location |
|---|---|
| Settings, bookmarks, user profiles, the account list, and the locations of server repositories on this Mac | Preferences domain com.rakuyo.spooky |
Themes, one .spookytheme file each |
~/Library/Application Support/Spooky/Themes/ |
The .spookyrepo folders that list server repositories in recent documents |
~/Library/Application Support/Spooky/Locations/ |
| Remote operations in the Activity window, kept for 7 days | ~/Library/Application Support/Spooky/Activity/ |
| The previous lists that the Activity window compares against | ~/Library/Application Support/Spooky/Baselines/ |
| Credentials saved to the Keychain | Keychain service com.rakuyo.spooky.remote.<host alias> |
| Hosting account tokens | Keychain service com.rakuyo.spooky.hosting.<instance address> |
| Connections and callbacks | Private /tmp/spooky-* directories, removed when the session closes |
| File copies for Quick Look and other apps | Private spooky-files-* temporary directories, removed when the repository closes |
On servers:
| Data | Location |
|---|---|
| The remote helper and its askpass, GPG, and ssh-keygen entry points | ~/.spooky/bin/, kept for later connections |
| Session runtime files | /tmp/spooky-*, removed when the session closes |
In repositories, pins, archives, parent branches, and branch review marks are stored in the repository's own Git configuration as branch.<name>.spooky-*. Repository settings are written to the same configuration.
Spooky is localized into English, Simplified Chinese, Traditional Chinese, Japanese, Korean, German, French, and Spanish. It follows the system language and falls back to English. Strings are in Sources/Spooky/Resources/<language>.lproj/.
When you add a string, add it to every language with the same format arguments. LocalizationTests fails when a language is missing a key, a translation is empty, format arguments don't match, or a key isn't used anywhere. Keys built at run time are registered in LocalizationTests.dynamicKeys.
The website at spooky.rakuyo.dev, with the home page and the user guide, is built from website/ with Astro and Starlight. It needs Node.js 24, which mise installs for the website tasks only:
# Install the dependencies and start the development server
mise run website:dev
# Run the website's tests, check types and internal links, and build the site into website/dist/
mise run website:buildPages quote the app's labels from Localizable.strings by resource key, so renaming or removing a key that the website uses breaks its build. The simulated window on the home page also takes its colors from BuiltinThemes.json and NamedColors.json. The app icon and the ghosts on the home page and the 404 page are drawn at build time by the app icon scripts in scripts/make-icon/. Screenshots are stored with Git LFS; install it before cloning to get them.
When the home page is opened on your machine (the development server, or a preview of the built site), a numbered grid covers the page and the header reads out where the top of the viewport and the ghost's center are, in grid cells, so you can point at where the scrolling ghost should do what. The published site doesn't show the grid.
GitHub Actions builds the website on pull requests that change it, and deploys it to GitHub Pages when it changes on main.
The code style follows RakuyoKit/swift:
# Format the code and fix what can be fixed automatically
mise run swift:format
# Check the code style
mise run swift:lintSwiftLint runs in strict mode, so warnings fail the check too. The other coding conventions are in AGENTS.md (in Chinese).
Maintainers release new versions from main:
# Open a release PR for version X.Y.Z; the channel defaults to stable
mise run release X.Y.Z [stable|beta|development]The script checks the version, the release notes in docs/release-notes/X.Y.Z/, and the state of the repository, then opens a release PR. Once it's merged, GitHub Actions bundles the app, signs the update, tags the merge commit, and creates the GitHub Release.
Releasing (in Chinese) has the details.
-
Before opening a pull request, run
mise run swift:lint,mise run build, andmise run test, and make sure they all pass. CI runs the same checks on every pull request and push tomain, and bundles the app as well -
If you change the app, launch it and check that your change works. M1 has the basic steps
-
AGENTS.md has the conventions for code, comments, logs, tests, branch names, commit messages, and pull requests. Coding agents such as Claude Code and Codex follow it too. It's in Chinese
-
Before bringing in outside code, make sure its license is compatible with GPL-3.0
Spooky is licensed under the GNU General Public License v3.0.
- Sparkle 2.10.0, used for updates. Licensed under the MIT License; the license ships with the app as
Contents/Resources/Sparkle-LICENSE.txt - highlight.js 11.12.0, used for syntax coloring. Copyright (c) 2006, Ivan Sagalaev. Licensed under the BSD 3-Clause License; the full license is in
Sources/Spooky/HighlightJS/LICENSEand ships with the app - swift-subprocess 1.0.1, used to launch Git and other subprocesses. Licensed under the Apache License 2.0; the license ships with the app as
Contents/Resources/Subprocess-LICENSE.txt