Git-Same

Mirror your GitHub org structure to the local filesystem: parallel clone, incremental sync, CLI, TUI dashboard, and a macOS Tauri app with Finder badges and workspace folder icons.

What It Does

+--------------------------------------+------------+------------------------------------+
│ GITHUB PLATFORM                      │    Sync    │ LOCAL FILE SYSTEM                  │
│ github.com                           │            │ /users/m/same-github/              │
+--------------------------------------+------------+------------------------------------+
│ github.com/manuelgruber              │   <<==>>   │ manuelgruber/                      │
│ github.com/manuelgruber/.github      │   <<==>>   │ manuelgruber/.github/              │
│ github.com/manuelgruber/dotfiles     │   <<==>>   │ manuelgruber/dotfiles/             │
+--------------------------------------+------------+------------------------------------+
│ github.com/zaai-com                  │   <<==>>   │ zaai-com/                          │
│ github.com/zaai-com/powernight       │   <<==>>   │ zaai-com/powernight/               │
│ github.com/zaai-com/clean-autofill   │   <<==>>   │ zaai-com/clean-autofill/           │
│ github.com/zaai-com/git-same         │   <<==>>   │ zaai-com/git-same/                 │
│ github.com/zaai-com/jekyll-aeo       │   <<==>>   │ zaai-com/jekyll-aeo/               │
+--------------------------------------+------------+------------------------------------+
│ github.com/company1                  │   <<==>>   │ company1/                          │
│ github.com/company1/example.ai       │   <<==>>   │ company1/example.ai/               │
+--------------------------------------+------------+------------------------------------+
│ 3 orgs · 7 repos                     │            │ 3 dirs · 7 repos                   │
+--------------------------------------+------------+------------------------------------+

One command discovers every repo across your GitHub orgs and mirrors them locally, cloning new repos in parallel, fetching updates for existing ones, and skipping repos with uncommitted changes. On macOS, the cask also installs Git-Same.app, FinderSync badges, and a background monitor (started during installation) so workspace status is visible in Finder.

Installation

macOS (signed + notarized cask):

brew install --cask zaai-com/tap/git-same

Linux and headless macOS (formula):

brew install zaai-com/tap/git-same-cli

The macOS cask ships the Tauri GUI app, Finder badges, monitor LaunchAgent, and CLI aliases. brew upgrade --cask git-same keeps the app and command-line tools current together.

Other installation methods

From crates.io

cargo install git-same

GitHub Releases

Download pre-built assets from GitHub Releases. Linux and headless macOS CLI builds are .tar.gz archives named git-same-<version>-<target-triple>.tar.gz (for example, git-same-3.1.0-aarch64-apple-darwin.tar.gz). macOS GUI builds are signed and notarized DMGs named git-same-<version>-<arch>.dmg.

Quick Start

Interactive (TUI)

git-same

Launches the full terminal UI with dashboard, sync, status, and workspace management, all via keyboard shortcuts.

CLI

git-same init          # 1. Create user config
git-same setup         # 2. Configure workspace (interactive wizard)
git-same sync          # 3. Clone new repos, fetch/pull existing
git-same status        # 4. Check repo status across orgs

Commands

Command	Description
git-same init	Create config file with sensible defaults
git-same setup	Interactive wizard to configure a workspace
git-same sync	Discover, clone new, fetch/pull existing repos
git-same status	Show git status across all local repos
git-same workspace	List workspaces, set default
git-same reset	Remove all config, workspaces, and cache
git-same monitor	Run or inspect the background status monitor
git-same refresh	Ask the running monitor to rescan immediately
git-same scan	Discover repos without cloning or syncing

git-same init

Initialize git-same configuration:

git-same init [-p <config-path>] [-f | --force]

Creates a config file at ~/.config/git-same/config.toml with sensible defaults.

git-same setup

Configure a workspace (interactive wizard):

git-same setup [--name <NAME>]

Walks through provider selection, authentication, org filters, and base path.

git-same sync

Sync repositories: discover, clone new, fetch/pull existing:

git-same sync [OPTIONS]

Options:
  -w, --workspace <WORKSPACE> Workspace to sync (path or unique folder name)
      --pull                  Use pull instead of fetch for existing repos
  -n, --dry-run               Show what would be done
  -c, --concurrency <N>       Number of parallel operations (1-32)
      --refresh               Force re-discovery (ignore cache)
      --no-skip-uncommitted         Don't skip repos with uncommitted changes

Discovering repos

Cloning & fetching

Completed

git-same status

Show status of local repositories:

git-same status [OPTIONS]

Options:
  -w, --workspace <WORKSPACE> Workspace to check (path or unique folder name)
  -o, --org <ORG>...          Filter by organization (repeatable)
  -d, --uncommitted                 Show only repositories with uncommitted changes
  -b, --behind                Show only repositories behind upstream
      --detailed              Show detailed status information

git-same workspace

Manage workspaces:

git-same workspace list              # List configured workspaces
git-same workspace default [WORKSPACE] # Set default workspace (path or unique folder name)
git-same workspace default --clear   # Clear default workspace

git-same reset

Remove all config, workspaces, and cache:

git-same reset [-f | --force]

git-same monitor

Run, control, or inspect the status monitor used by the macOS Finder extension and app:

git-same monitor [OPTIONS]

Options:
      --status           Show state, PID, and last scan (works without a config)
      --start            Enable and start the background monitor (macOS)
      --stop             Stop monitoring and keep it stopped until the next --start
      --uninstall        Stop and remove the background monitor (macOS)
      --foreground       Run in the foreground (the default without a control flag)
      --interval <SECS>  Foreground full-scan interval, overriding config.toml

The control flags are mutually exclusive, and --interval applies only to foreground runs. --config is rejected for the control flags: the background monitor always uses the default configuration. The older daemon subcommand remains as a compatibility alias.

The background monitor on macOS. Monitoring runs as a separate helper under a per-user LaunchAgent, independent of Git-Same.app: closing the app does not stop it, and it starts again at every login.

Install method	When the monitor is set up
Homebrew cask	During brew install / brew upgrade, without opening the app
App from the DMG	On first launch of Git-Same.app
Homebrew formula, cargo install, downloaded CLI	On the first gisa sync, gisa refresh, gisa init, gisa setup, gisa scan --register, or TUI launch

After that, the app and those same CLI commands check on it and start it again if it stopped unexpectedly. A healthy monitor is never restarted. Read-only commands (status, workspace, scan without --register, sync --dry-run) and anything run with --config never touch the service. Set GIT_SAME_DISABLE_MONITOR_AUTOSTART=1 to suppress this automatic management entirely; explicit --start / --stop still work.

Stop means stop. gisa monitor --stop (or Stop in the app) is remembered as [monitor] autostart = false and in launchd. App launches, CLI use, upgrades, logins, and restarts all leave monitoring off until you run gisa monitor --start or press Start. Saving settings in the app never changes this. gisa reset of the global configuration stops monitoring first.

The first scan. While the monitor performs its initial scan, --status and the app report starting. Large workspaces can take a few minutes; nothing restarts it meanwhile, and gisa refresh reports that the initial scan is in progress instead of failing. Finder badges additionally need the Git-Same Badges extension enabled, and show current data once that first scan completes.

Where things live.

What	Path
Helper and install record	~/Library/Application Support/com.zaai.git-same/monitor/
LaunchAgent	~/Library/LaunchAgents/com.zaai.git-same.monitor.plist
Logs	~/Library/Logs/git-same/monitor.log and monitor.err.log
Status and socket	~/Library/Group Containers/group.57KL6Y7V32.com.zaai.git-same/

Headless sessions. Over SSH with no desktop login, the monitor is installed and reported as deferred; it starts at the next login. gisa monitor in the foreground works without a desktop session. Linux and Windows have no background service: run gisa monitor yourself.

Recovery. gisa monitor --status shows the state and any error detail. gisa monitor --start repairs a missing helper or LaunchAgent; an interrupted install is rolled back automatically by the next command. gisa monitor --uninstall removes the helper and LaunchAgent but keeps repositories, configuration, and logs. If brew uninstall --cask git-same fails because its Caskroom directory was deleted by hand, run brew uninstall --force --cask git-same and then gisa monitor --uninstall.

A failed --start leaves monitoring off. --stop is remembered twice, as [monitor] autostart = false and as a disabled launchd service, and a --start that fails does not put either half back. Refused because a foreground gisa monitor is already running, both halves of the stop survive untouched. Failing later, on a helper that cannot be copied or signed or on a launchd error, it can leave the two halves disagreeing. In every case monitoring is still not running, and it stays off across logins and restarts until a --start succeeds. Run gisa monitor --status for the reason, fix it, and run gisa monitor --start again until --status reports running or starting.

git-same refresh

Ask the running monitor to rewrite Finder/app status immediately:

git-same refresh [--path <DIR>]

Use this after manually changing workspace folders, deleting repos, or debugging Finder badges. Without --path, every monitored workspace is refreshed.

git-same scan

Scan a directory tree for existing workspace markers:

git-same scan [PATH] [--depth <N>] [--register]

Use --register to add discovered workspaces to your config automatically.

Aliases

Git-Same installs multiple binary names so you can use whichever you prefer:

Command	Description
git-same	Primary binary (always available)
gitsame	No-hyphen alias (symlink)
gitsa	Short alias (symlink)
gisa	Shortest alias (symlink)
git same	Git subcommand (requires git-same in PATH)

Install method differences: Homebrew cask (brew install --cask zaai-com/tap/git-same) and the headless formula (brew install zaai-com/tap/git-same-cli) both install all aliases automatically. cargo install git-same installs only the primary binary.

All examples in this README use git-same, but any alias works interchangeably.

macOS App and Finder Badges

The cask installs Git-Same.app, the CLI aliases, a FinderSync badge extension, and a monitor LaunchAgent. The app reads the same config as the CLI and shows workspace status from the monitor. Finder badges use the monitor's status file, and workspace root folders get a custom Git-Same folder icon unless [ui] custom_folder_icon = false is set.

Useful checks:

gisa monitor --status   # State, PID, last scan, and any error detail
gisa refresh            # Force an immediate status refresh
gisa monitor --start    # Start (or repair) the background monitor
gisa monitor --stop     # Stop monitoring until the next --start

If Finder reserves badge space but no Git-Same badges render, check System Settings -> Login Items & Extensions. Google Drive's FinderSync extension can prevent peer badge images from appearing; disabling Google Drive's Finder extension has been the confirmed workaround in affected environments.

Requirements

Git-Same depends on two external tools at runtime:

• git: Git-Same shells out to git for all repository operations (clone, fetch, pull, and status). Without it, no git operations can run.
• gh (GitHub CLI): Git-Same calls gh auth token to obtain GitHub API tokens for repo discovery and gh api user to resolve your username. Without it, Git-Same cannot authenticate with the GitHub API.

Installing and authenticating gh

# Install GitHub CLI
brew install gh  # macOS
# or: sudo apt install gh  # Ubuntu

# Authenticate
gh auth login

# Git-Same will now use your gh credentials
git-same sync

TUI Mode

Running git-same without a subcommand launches the interactive terminal UI.

Screens

Screen	Purpose	Key bindings
Dashboard	Overview with status tabs, search, and sync actions	s: Start sync, p: Show sync progress, t: Refresh status, w: Workspaces, e/i: Settings, /: Search repositories, [←]/[→]: Switch tabs, [↑]/[↓]: Move within tab, Enter: Open selected repo folder
Workspace Selector	Pick, inspect, and create workspaces	[←]/[→] or Tab: Switch pane, [↑]/[↓]: Move or scroll, Enter: Select workspace or create new, d: Set default, n: New workspace, c: Expand/collapse config, f: Open folder
Setup Wizard	Interactive workspace configuration	Step-by-step prompts for requirements, provider, authentication, orgs, path, and confirmation
Sync Progress	Live sync progress and post-sync results	p/Esc: Hide or go back, [←]/[→]: Switch result filters when finished, [↑]/[↓]: Move or scroll, a: All, u: Updated, f: Failed, x: Skipped, c: Changelog, h: History, Enter: Expand selected repo commit detail
Settings	View requirements and adjust run options	Tab/[↑]/[↓]: Move, c: Open config folder, d: Toggle dry run, m: Toggle fetch/pull mode, Esc: Back

Examples

Sync all repositories in default workspace

git-same sync

Sync with pull mode for a specific workspace

git-same sync --workspace work --pull

Check which repositories have uncommitted changes

git-same status --uncommitted

Dry run to see what would be synced

git-same sync --dry-run

License

MIT License - see LICENSE for details

Roadmap

• GitHub support
• Parallel cloning
• Smart filtering
• Progress bars
• Interactive TUI mode
• Workspace management
• GitLab support
• Bitbucket support
• Repo groups
• Web dashboard

---

Building from source or contributing? See DEVELOPMENT.md.