gitstow 0.2.6

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

gitstow

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

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
# or: pip install gitstow

# First-run setup (optional — works without it)
gitstow onboard

# 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

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 # Dirty repos in active workspace

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 [e-mail]: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

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. Auto-refreshes row status every 30 seconds. Binds 127.0.0.1 only (arbitrary git execution must not be LAN-reachable). Click Shutdown in the footer — or Ctrl+C — to stop.

Interactive Dashboard (TUI)

gitstow tui    # Keyboard-driven terminal dashboard (SSH-friendly)

JSON Output

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

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

Commands

Command	Description
Core
gitstow add <url> [urls...]	Clone repos into organized structure
gitstow pull	Bulk update all (or filtered) repos
gitstow list	List repos grouped by owner/workspace
gitstow status	Git status dashboard
gitstow remove <repo>	Remove a repo from tracking
gitstow migrate <path>	Adopt existing repos into structure
Workspaces
gitstow workspace list	List all configured workspaces
gitstow workspace add <path>	Add a new workspace
gitstow workspace remove <label>	Remove a workspace
gitstow workspace scan <label>	Discover and register repos on disk
Repo Management
gitstow repo freeze <repo>	Skip repo during pull
gitstow repo unfreeze <repo>	Re-enable pulling
gitstow repo tag <repo> <tags...>	Add tags to a repo
gitstow repo untag <repo> <tag>	Remove a tag
gitstow repo tags	List all tags with counts
gitstow repo info <repo>	Detailed repo info
Power
gitstow exec <command>	Run a command in every repo
gitstow search <pattern>	Grep across all repos (uses ripgrep)
gitstow open <repo>	Open in editor, browser, or Finder
gitstow stats	Collection statistics and disk usage
Sharing
gitstow collection export	Export collection as YAML, JSON, or URLs
gitstow collection import <file>	Import a collection from file
Shell
gitstow shell setup	Show shell integration instructions
gitstow shell init	Print shell functions to source in rc file
gitstow shell pick	fzf-powered repo picker
gitstow shell completions	Tab completion for repo names, workspaces, tags
gitstow tui	Interactive terminal dashboard
gitstow fetch	Fetch all remotes — update ahead/behind counts without merging
gitstow ui	Launch local browser dashboard (http://127.0.0.1:7853)
gitstow update	Upgrade gitstow itself from PyPI (detects pipx / pip / editable)
gitstow update --check	Check PyPI for a newer version without installing
Config
gitstow config show	Show current config and workspaces
gitstow config set <key> <value>	Change a setting
gitstow onboard	First-run setup wizard
gitstow doctor	Health check
gitstow install-skill	Install Claude Code skill
gitstow setup-ai	Auto-detect AI tools and configure integration

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

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. Zero-config start — gitstow add owner/repo works immediately with sensible defaults.

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.

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

MIT