git-iter-go

git-iter

git-iter is a high-performance CLI tool to discover, search, and run commands concurrently across multiple local git repositories.

It supports parallel execution controls, per-process timeouts, fail-fast behavior, and structured output formats (JSON Lines and Markdown reports), alongside a built-in Model Context Protocol (MCP) server for LLMs and agents.

Features

• Concurrent Execution: Run commands across multiple repositories simultaneously (-p, --max-procs).
• Flexible Discovery: Recursively discover git repositories (-r, --repos-root) or provide arbitrary discovery shell commands (--list-repos).
• Filtering & Limiting:
  • Filter repositories using regex patterns.
  • Filter by repository state (-d, --dirty-only, -c, --clean-only).
  • Filter by branch state (--default-branch-only, --not-default-branch-only, --branch).
  • Filter by origin remote URL regex pattern (--remote-url).
  • Sort (--sort, --sort-reverse) and limit (-n, --limit).
• Multiple Output Formats:
  • text (default): Real-time streaming output to stdout/stderr.
  • json: Structured JSON Lines (output.Result / output.RepoResult / output.FileResult).
  • markdown / md: Markdown reports with collapsible details and summary tables.
• Dedicated Subcommands:
  • do: Run arbitrary commands in matching repositories.
  • grep: Run git grep with repository path prefixing.
  • diff: Run git diff non-interactively (--no-pager) by default, with opt-in pager (-i, --interactive).
  • status (st): Inspect status across repositories.
  • ls-files (lsf): List tracked/untracked files with repository path prefixing.
  • pull: Pull with optional default branch checkout and switch-back (-s, --switch-default, -b, --switch-back).
  • fetch: Fetch with optional default branch restriction (-s, --default).
  • list (ls): List matching repository paths.
  • get: Resolve or clone a repository by URI under --repos-root, or list repository paths when URI is omitted.
  • worktree (wt): Manage git worktrees across repositories (list, add -b, remove -f, prune --all --dry-run).
  • read: Execute commands for repository paths fed via stdin.
  • mcp: Model Context Protocol server over stdio for LLM integration.

Installation

Via go install

go install github.com/berquerant/git-iter-go/cmd/git-iter@latest

Pre-built Binaries

Download pre-compiled binaries for Linux, macOS, or Windows from GitHub Releases.

Usage Overview

git-iter [command] [flags]

Global Flags & Configuration

Settings can be specified via CLI flags or environment variables (GIT_ITER_*):

Common Examples

1. Execute Commands Across Repositories (do)

Arguments before -- are regex patterns filtering repository paths. Arguments after -- are the command and arguments to run:

# Run git status in all repositories under ~/src
git-iter -r ~/src do -- git status -s

# Run in parallel with 4 workers
git-iter -r ~/src -p 4 do -- git fetch --prune

# Only target dirty repositories matching regex "backend"
git-iter -r ~/src -d do backend -- git status -s

# Output structured JSON Lines
git-iter -r ~/src -o json do -- git rev-parse HEAD

2. Search Code (grep)

Prefixes each match with the repository path:

# Search for TODO in all repositories
git-iter -r ~/src grep -- TODO

# Forward git grep flags
git-iter -r ~/src grep -- -n -i "fixme"

# Generate a Markdown report
git-iter -r ~/src -o markdown grep -- -n "TODO" > todo_report.md

3. Check Diff Across Repositories (diff)

By default, diff runs with --no-pager so output streams cleanly without blocking:

# Show summary stats of uncommitted changes
git-iter -r ~/src diff -- --stat

# Only inspect dirty repositories
git-iter -r ~/src -d diff

# Run interactively with pager enabled
git-iter -r ~/src diff -i

4. Repository Status (status / st)

# Show short status across all repositories
git-iter -r ~/src status

# Emit JSON Lines for automation
git-iter -r ~/src -o json status

5. Repository Discovery, Cloning & Pipelining (list, get & read)

# List all discovered repositories
git-iter -r ~/src list

# Resolve or clone a repository by URI under ~/src and print its absolute path
git-iter -r ~/src get https://github.com/berquerant/git-iter-go.git

# Narrow down with patterns and pipe into read
git-iter -r ~/src list "service-.*" | git-iter read git pull

# Run shell commands with flags (use "--" so flags like "-c" are not parsed as git-iter options)
git-iter -r ~/src list | git-iter read -- bash -c "git status -s"

6. Pull and Fetch Across Repositories

# Pull only the default branch (e.g. main/master) and switch back
git-iter -r ~/src pull --switch-default --switch-back

# Fetch only the default branch from origin
git-iter -r ~/src fetch --default

7. Manage Git Worktrees (worktree / wt)

Worktrees for a repository <repos-root>/<DIR> are placed at <worktree-root>/<DIR>/<BRANCH>:

# List worktrees for the current repository
git-iter -r ~/src wt list

# List all worktrees across all repositories under worktree-root
git-iter -r ~/src wt list -a

# List unique main repository paths that have worktrees
git-iter -r ~/src wt list --repo -a

# Create a worktree for an existing branch in the current repository and print its path
git-iter -r ~/src wt add feat/existing

# Create a new branch from origin/main in a new worktree and print its path
git-iter -r ~/src wt add -b feat/new origin/main

# Remove a worktree by branch name for the current repository
git-iter -r ~/src wt remove feat/new

# Force-remove a worktree even if dirty or containing untracked files
git-iter -r ~/src wt remove -f feat/new

# Prune worktrees merged into the default branch for the current repository
git-iter -r ~/src wt prune

# Dry-run prune across all repositories with worktrees
git-iter -r ~/src wt prune --all --dry-run

Model Context Protocol (MCP) Server

git-iter can run as an MCP server communicating over standard input/output (stdio), exposing tools to AI assistants (Claude Desktop, Cursor, Antigravity, etc.):

git-iter -r ~/src mcp

Available MCP Tools

• git_iter_list: Discover and list repositories under the configured root.
• git_iter_status: Run git status in matching repositories.
• git_iter_diff: Run git diff in matching repositories.
• git_iter_grep: Run git grep across matching repositories.
• git_iter_ls_files: Run git ls-files across matching repositories.
• git_iter_worktree_list: Discover and list git worktrees (or unique main repositories with repo=true) under the worktree root.
• git_iter_worktree_add: Create a git worktree for the target repository (disabled by default for security, opt-in via --enable-worktree).
• git_iter_worktree_remove: Remove a git worktree for the target repository (disabled by default for security, opt-in via --enable-worktree).
• git_iter_worktree_prune: Remove worktrees merged into the default branch and prune stale administrative files (disabled by default for security, opt-in via --enable-worktree).
• git_iter_get: Resolve or clone a repository by URI under the root directory, or list discovered repositories (disabled by default for security, opt-in via --enable-get).
• git_iter_do: Execute arbitrary commands in matching repositories (disabled by default for security, opt-in via --enable-do).

To enable optional tools for the MCP server:

git-iter -r ~/src mcp --enable-do --enable-get --enable-worktree

Development

Requires Go 1.24+ and mise.

# Run lint, test, and build (default)
mise run default

# Run tests with race detection and coverage
mise run test

# Run linters
mise run lint

# Check third-party license notices
mise run licenses

License

MIT License. See LICENSE and NOTICE for third-party software notices.