git-router

Route SSH keys, HTTPS credentials, and committer identity by matching the org/namespace in git remote URLs. Replaces SSH host aliases, url.<base>.insteadOf rules, and per-directory gitconfig includes.

Install · Quick start · Commands · Config · How it works · Security

---

Install

Linux

Repository	Instructions
crates.io	cargo install git-router
Homebrew	brew install misfitdev/tap/git-router

Or download a prebuilt binary from GitHub Releases.

macOS

Repository	Instructions
Homebrew	brew install misfitdev/tap/git-router
crates.io	cargo install git-router

Or download a prebuilt binary from GitHub Releases.

Every release includes SHA256 checksums and SLSA build provenance attestations, verifiable with:

gh attestation verify git-router-*.tar.gz --owner misfitdev

Quick start

# Wire git-router into global gitconfig
git router init

# Add routes (with optional per-route identity)
git router add github.com personal --ssh-key ~/.ssh/personal.pub \
  --user-name "Tucker" --user-email "tucker@personal.dev"
git router add github.com work-org --ssh-key ~/.ssh/work.pub --token ghp_xxxx \
  --user-name "Tucker DeWitt" --user-email "tucker@work.com"
git router add gitlab.com my-group --ssh-key ~/.ssh/gitlab.pub

# Verify setup
git router doctor

Now git clone, git fetch, and git push automatically use the right SSH key, HTTPS token, and committer identity based on the org in the remote URL.

Commands

Command	Description
git router init	Wire git-router into global gitconfig (idempotent)
git router add <host> <org> [OPTIONS]	Add or update a route
git router show	Print all routes with full details
git router list	Print routes as one-liners
git router remove <host> <org>	Remove a route
git router doctor	Verify config, keys, and gitconfig wiring

Options for add: --ssh-key PATH, --token TOKEN, --user-name NAME, --user-email EMAIL

Config

Routes live in ~/.config/git-router/config.toml:

[[route]]
host = "github.com"
org = "personal"
ssh_key = "~/.ssh/personal.pub"
user_name = "Tucker"
user_email = "tucker@personal.dev"

[[route]]
host = "github.com"
org = "work-org"
ssh_key = "~/.ssh/work.pub"
token = "ghp_xxxx"
user_name = "Tucker DeWitt"
user_email = "tucker@work.com"

[[route]]
host = "gitlab.com"
org = "my-group"
ssh_key = "~/.ssh/gitlab.pub"

user_name and user_email are optional. Routes without them fall back to whatever user.name/user.email is set in your global gitconfig.

Route matching

The <org> argument is separate from <host> and can contain slashes for nested namespaces:

git router add gitlab.com acme --ssh-key ~/.ssh/gl-acme.pub
git router add gitlab.com acme/foo --ssh-key ~/.ssh/gl-foo.pub

When resolving a remote like gitlab.com:acme/foo/bar.git, git-router tries progressively shorter path prefixes until it finds a match: acme/foo matches before falling back to acme.

How it works

git-router is a single binary that git invokes at two points during remote operations:

SSH wrapper (core.sshCommand = git-router ssh-wrap) -- for SSH remotes. Parses the host and org from the SSH arguments, looks up the matching route, and execs ssh with the correct IdentityFile.

Credential helper (credential.helper = git-router credential-helper) -- for HTTPS remotes. Reads the host and path from stdin, matches a route, and returns the token.

Identity -- git router init generates gitconfig includeIf fragments that set user.name and user.email based on the remote URL. This is static config, not a runtime hook -- git evaluates it directly. Requires git 2.36+.

Design constraints

• Never modifies ~/.ssh/config
• Passes through on no match -- never blocks a git operation
• No daemons, no background processes, no temp files
• Atomic config writes (write-then-rename)
• Exit codes pass through from ssh or credential operations

Security

See SECURITY.md for the vulnerability reporting policy.

License

MIT