gitstow

A git repository library manager — clone, organize, and maintain collections of repos you learn from.

gitstow.com · PyPI · Changelog

Why?

AI-assisted development has created a new relationship with open source. Developers increasingly maintain local clones of repositories they study and reference, not just repos they contribute to. gitstow manages this collection as a first-class concern.

Existing tools solve parts of this:

• ghq (3.5k stars) auto-organizes repos by host/owner/repo — but can't pull, status-check, or run commands across them.
• gita (1.8k stars) runs bulk git operations — but doesn't organize or auto-structure anything.

gitstow combines the best of both: paste a URL → auto-organized → bulk pull, freeze, tag, and manage your entire collection. Works across multiple workspaces — open-source collections, active projects, and more.

Quick Start

pipx install gitstow   # recommended — full install: CLI + browser dashboard
# or: pip install gitstow

# No pipx? Most Linux distros don't ship it by default:
#   sudo apt install pipx      (Debian/Ubuntu)
#   brew install pipx          (macOS)

# First-run setup — creates your first workspace, sets your default host
gitstow onboard
# ...or skip the wizard and add a workspace directly:
#   gitstow workspace add ~/oss --label oss

# Add repos (GitHub shorthand or full URLs)
gitstow add anthropic/claude-code
gitstow add https://gitlab.com/group/project

# Update everything
gitstow pull

# See your collection
gitstow list

Prefer a GUI? Run gitstow ui — a local dark-themed browser dashboard opens automatically. Dirty state, branch deltas, Pull / Pull-all, add / remove / freeze / tag, workspace CRUD, collection export/import — all in one tab you leave open. See Browser Dashboard.

Features

Workspaces

# Track open-source repos (structured: owner/repo layout)
gitstow workspace add ~/oss --label oss --layout structured

# Track your active projects (flat: repos directly in folder)
gitstow workspace add ~/labs/projects --label active --layout flat --auto-tag active

# Scan to discover existing repos
gitstow workspace scan active

Auto-Organization

gitstow add anthropic/claude-code facebook/react torvalds/linux

Multiple URLs clone concurrently (bounded by parallel_limit, default 6) — a mismatched remote on an existing path errors instead of silently registering, and duplicate URLs in the same invocation are deduped.

Creates (in a structured workspace):

~/oss/
├── anthropic/
│   └── claude-code/
├── facebook/
│   └── react/
└── torvalds/
    └── linux/

Bulk Operations

gitstow pull                    # Update all repos across all workspaces
gitstow -w oss pull             # Only update oss workspace
gitstow pull --tag ai           # Only repos tagged 'ai'
gitstow pull --exclude-tag stale # Everything except stale repos
gitstow status                  # Git status dashboard
gitstow -w active status --dirty # Repos with local changes in active workspace
gitstow diff <repo>              # View a repo's uncommitted changes (staged/unstaged) — view-only
gitstow diff <repo> --staged     # View staged changes only
gitstow diff <repo> --json       # List changed files (staged/unstaged/untracked) as JSON

status shows local changes as a composition (e.g. "2 modified · 1 staged · 3 untracked") rather than a single "dirty" bucket, and keeps the remote relationship (ahead/behind/diverged) in its own column. diff prints the colored git diff for a single repo (clean repos print "no local changes").

Freeze & Tags

gitstow repo freeze facebook/react   # Skip during pull
gitstow repo tag anthropic/claude-code ai tools
gitstow pull --tag ai                # Update only AI repos
gitstow repo tags                    # List all tags

Migrate Existing Repos

gitstow migrate ~/old-projects/some-repo   # Auto-detects owner/repo from remote

Any Git Host

gitstow add anthropic/claude-code              # GitHub (default)
gitstow add https://gitlab.com/group/project   # GitLab (nested groups work)
gitstow add git@bitbucket.org:owner/repo.git   # Bitbucket
gitstow add https://codeberg.org/owner/repo    # Codeberg

AI Integration

gitstow is designed to be used primarily through AI tools. The Claude Code skill is installed automatically during onboarding and auto-updates on version bumps:

gitstow install-skill   # Or: gitstow onboard (includes this)
# Then in Claude Code: "add this repo" or "update my repos"

MCP server is also available for non-Claude-Code AI tools (Claude Desktop, Cursor, etc.) via pip install gitstow[mcp]. See docs/user/configuration.md for setup. Note: MCP tools are always loaded into context and cost tokens even when not in use — the skill has zero overhead when inactive.

Run Commands Across Repos

gitstow exec -- git log -1 --oneline      # Last commit in each repo
gitstow exec --tag python -- wc -l README.md  # Line count in Python repos

Search Across Repos

gitstow search "TODO"                     # Grep everything
gitstow search "def main" --glob "*.py"   # Only Python files
gitstow search "error" --tag ai -i        # Case-insensitive, AI repos only

Share Your Collection

gitstow collection export -o my-repos.yaml   # Export as portable YAML
gitstow collection import my-repos.yaml      # Import on another machine
gitstow collection export --format urls      # Plain URL list

Shell Integration

eval "$(gitstow shell init)"    # Add to ~/.zshrc or ~/.bashrc
gs                               # cd into a repo (fzf picker)
gse                              # Open repo in editor (fzf picker)
gsp                              # gitstow pull shorthand

Browser Dashboard

gitstow ui                  # opens http://127.0.0.1:7853 in your browser
gitstow ui --port 8080
gitstow ui --no-browser
gitstow ui --tailscale      # also serve on your Tailscale address (VPS-friendly)

Persistent local web dashboard for daily repo management — a tab you leave open. Shows dirty state across your library, pulls single repos or all-of-them with a parallel summary panel, adds/removes repos, edits tags, freezes stale ones. The repo detail page has a Changes section — staged/unstaged/untracked groups, click a file to expand its colored line diff. Auto-refreshes row status every 30 seconds. Click Shutdown in the footer — or Ctrl+C — to stop.

Private by default: binds 127.0.0.1 (arbitrary git execution must not be LAN-reachable). Running gitstow on a VPS or home server? Enable Tailscale access and the dashboard is also served on your tailnet address — open it from any of your devices, encrypted by WireGuard, invisible to the public internet. It never binds 0.0.0.0:

gitstow config set ui_tailscale true   # every gitstow ui from now on
gitstow ui --tailscale                 # or per-run

You can also flip it on the dashboard's own Settings page — it takes effect the next time you start gitstow ui. If Tailscale isn't running, gitstow ui warns and serves localhost only.

JSON Output

Every command supports --json for scripting and AI consumption:

gitstow list --json
gitstow pull --json --quiet
gitstow status --json

Commands

All commands accept -w <label> to filter to a specific workspace.

Configuration

Config lives at ~/.gitstow/config.yaml:

workspaces:
  - path: ~/oss
    label: oss
    layout: structured
  - path: ~/labs/projects
    label: active
    layout: flat
    auto_tags: [active]
default_host: github.com
prefer_ssh: false
parallel_limit: 6
ui_tailscale: false   # serve `gitstow ui` on your Tailscale address too

Repo metadata at ~/.gitstow/repos.yaml (nested by workspace):

oss:
  anthropic/claude-code:
    remote_url: https://github.com/anthropic/claude-code.git
    frozen: false
    tags: [ai, tools]
    added: '2026-04-05'
active:
  gitstow:
    remote_url: https://github.com/rishmadaan/gitstow.git
    tags: [active]
    added: '2026-04-05'

How It Works

1. Workspaces — Each workspace is a directory with a layout mode (structured = owner/repo, flat = just repo). Repos are organized across workspaces, tagged, and managed as a unified collection.
2. Folder-as-state — The directory structure is the primary source of truth. repos.yaml supplements with metadata (frozen, tags, timestamps).
3. Error isolation — One bad repo never stops operations on others. Failures are collected and reported in a summary.
4. Parallel execution — Bulk operations use asyncio with a semaphore (default 6 concurrent) to prevent SSH connection storms.
5. Explicit state — gitstow never invents a workspace. A fresh install has none, and commands that need one say exactly how to create it. Zero workspaces is a valid state: you can remove your last workspace and gitstow will simply say so.

A note on folder structure

Structured workspaces organize repos as owner/repo/ (e.g., ~/oss/anthropic/claude-code/). Unlike ghq which includes the host (root/github.com/owner/repo/), we omit it for simplicity.

Flat workspaces skip the owner directory entirely — repos are just workspace/repo-name/. Use flat layout for directories where you already have projects organized your own way.

Troubleshooting

gitstow: command not found — Make sure the install location is on your PATH. With pipx this is automatic. With pip, you may need python3 -m gitstow or add ~/.local/bin to your PATH.

SSH clone fails with "Permission denied (publickey)" — Your SSH key isn't configured for the git host. Either add your key (ssh-add) or use HTTPS: gitstow config set prefer_ssh false.

No workspaces configured — Expected on a fresh install, and after removing your last workspace. gitstow never invents one. Run gitstow workspace add <path> --label <name> or gitstow onboard.

Workspace directory doesn't exist — Run gitstow doctor to check workspace health. Create missing directories or update the path with gitstow workspace add.

gitstow doctor — Run this first when something isn't working. It checks git installation, config files, and workspace integrity.

Development

git clone https://github.com/rishmadaan/gitstow
cd gitstow
pip install -e ".[dev]"
pytest
ruff check src/

Release from a main branch with no tracked changes:

bash scripts/release.sh 0.2.6 "short release note"

The script bumps pyproject.toml and src/gitstow/__init__.py, commits the bump, creates vX.Y.Z, and pushes the commit plus tag. Pushing the tag publishes to PyPI.

See CONTRIBUTING.md for the full guide.

License

Copyright (c) 2026 rishmadaan. Licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later).

You may use gitstow commercially and modify it. When distributing covered versions, you must comply with the GPL, including its corresponding-source requirements. Simply managing a repository with gitstow does not change that repository's license.

Versions through 0.7.2 remain MIT-licensed; subsequent versions use GPL v3 or later, starting with version 0.8.0. Bundled htmx and fonts retain their BSD and SIL Open Font licenses; see NOTICE for attribution and scope.