Fleet-scale Git automation

gix keeps large fleets of repositories healthy.

Automate folder normalization, remote alignment, branch refresh, and workflow-driven maintenance with one CLI — purpose-built for teams juggling hundreds of repos.

Install gix Read the docs

Go 1.25+, Git/GitHub first. Safe defaults, explicit safeguards.

gix workflow configs/account-rename.yaml \
  --roots ~/Development \
  --var namespace_old=github.com/old/org \
  --var namespace_new=github.com/new/org \
  --yes

Why gix?

Fleet Awareness

Discover repositories under one or more roots, skip nested duplicates, and run the same command everywhere without shell scripts.

Confident Automation

Domain-specific safeguards, “require clean” checks, interactive prompts, and a structured reporter ensure every operation is auditable.

Workflows, Not Bash

Describe multi-step plans (folder rename, remote update, git operations, PR creation) declaratively with YAML or run the built-in presets.

Multi-Repo Git Hygiene

Fix remotes, convert protocols, rename directories to canonical names, purge stale files, and refresh branches through one CLI.

LLM Helpers

Optional integrations assist with commit messages or changelog summaries while keeping human approvals in the loop. Configure ordered llm.openai and llm.llm_proxy connection profiles.

Stack-Friendly

Every command runs through the same workflow engine, so CLI, automation, and CI all produce consistent logs and summaries.

Local Audit Workspace

Launch a typed browser audit, queue remediation actions for review, and apply only the changes you approve.

Use cases we see every week

Platform Teams

Keep SDK repos aligned to the same branch default and remote protocol.
Roll out template updates by running workflows across every language pack.
Inspect responsive audits in the terminal, export full-value CSV for compliance reviews, or review queued fixes in the local browser workspace.

Security & Compliance

Ensure `.gitignore` and LICENSE files are present everywhere.
Trigger namespace rewrites after an organization rename.
Remove sensitive files from history with the `files rm` workflow.

Developer Tooling

Bootstrap personal defaults with gix init or system defaults with gix init --system.
Refresh dozens of example repos nightly to keep mergable branches.
Automate release tagging across mirrored repositories.

Get started in minutes.

Install the CLI, point it at your workspace, and let gix bring your repositories into a consistent, inspectable shape.

go install github.com/tyemirov/gix@latest
gix init to create ~/.gix/config.yml.
gix audit --roots ~/Development for a first pass.
gix --web --roots ~/Development to review typed audit findings and queue changes before applying them.

Config controls reusable defaults for roots, remotes, logging, confirmation prompts, clean-worktree policy, LLM provider/model settings, and workflow operations. The generated file gives llm.llm_proxy priority 1, selects Meta Muse inside that profile, and references ${LLM_PROXY_SECRET_KEY}. The direct llm.openai profile has priority 2 and interpolates ${OPENAI_API_KEY}, so it is attempted after a proxy request failure. Placeholders resolve only from the process environment; gix does not load dotenv files.

Documentation

README — command overview ARCHITECTURE — internals & design Web audit workspace — queued remediation ISSUES — roadmap & change log

Everyday Workflows

Normalize Folders

gix folder rename --roots ~/Development --owner --yes

Rename directories to match owner/repo naming so your filesystem mirrors GitHub.

Fix Remotes

gix remote update-to-canonical --owner tyemirov --roots ~/Projects

Ensure every repository’s origin points at the canonical GitHub slug.

Convert Protocols

gix remote update-protocol --from https --to git --roots ~/Work --yes

Switch entire trees over to SSH (or vice versa) without touching each repo manually.

Refresh Branches

gix sync master --stash --roots ~/Fleet

Stash tracked changes, jump to master, pull updates, and restore your work.

Run a Workflow

gix workflow configs/maintenance.yaml --roots ~/Fleet --yes

Chain rename, remote updates, git operations, and PR creation with one declarative file.

Audit Everything

gix audit --roots ~/Fleet --all --format csv > audit.csv

Capture CSV output for branch defaults, owners, remote protocols, and more.

Review Audit Fixes Locally

gix --web --roots ~/Fleet

Inspect typed audit rows, queue fixes, and apply only the reviewed batch from the local browser workspace.

Architecture at a Glance

Cobra + Strict Configuration

All commands live under cmd/cli with shared flags, one canonical YAML configuration path, and logging.
Workflow Engine

The internal workflow package plans, executes, and reports each operation, sharing discovery, prompts, and logging across commands.
Task Runner + Reporter

pkg/taskrunner wires dependencies and now emits compact summaries when multiple repositories run.
Domain Packages

internal/repos, internal/branches, and friends isolate Git/GitHub logic so workflows stay focused.

Recipes & Playbooks

Bulk switch and refresh branches

Branch Fleet

Confirm the worktrees are clean or use --stash to store tracked changes.
Run gix sync master --stash --roots ~/Fleet.
Review the summary to see which repositories switched, skipped, or warned.

gix sync master --stash --roots ~/Fleet

Convert all remotes to SSH

Remote Hygiene

Inspect current protocols with gix audit --roots ~/Repos.
Execute gix remote update-protocol --from https --to git --roots ~/Repos --yes.
Use the summary to confirm warnings (e.g., missing remotes).

gix remote update-protocol \
  --from https \
  --to git \
  --roots ~/Repos --yes

Roll out a repo workflow file

Workflow Rollout

Author a workflow (example below) describing the desired steps.
Run gix workflow ./configs/maintenance.yaml --roots ~/Fleet --yes.
Inspect per-repo logs plus the summary line (warnings/errors).

workflow:
  - step:
      name: normalize
      command: ["folder", "rename"]
      with:
        include_owner: true
  - step:
      name: remotes
      after: ["normalize"]
      command: ["remote", "update-to-canonical"]

Learning Hub

Anatomy of a Workflow

Commands, steps, safeguards, templating, and summaries all flow through internal/workflow. The engine now plugs into pkg/taskrunner, which prints a concise summary when multiple repositories run.

Recipes Library

Namespace rewrite → gix workflow namespace --var namespace_old=... --var namespace_new=...
License seeding → gix workflow license --var license_template=mit
GHCR cleanup → gix packages delete --roots ~/Containers --yes

Dive Deeper

Ready to automate your fleet?

Install gix with Go 1.25+, point it at your repositories, and let it keep your fleet in shape.

Download Release Read the README