Documentation

Complete guide to using brgit for managing multiple Git identities

Installation

Linux

curl -L https://github.com/byterings/brgit/releases/latest/download/brgit-linux-amd64 -o brgit
chmod +x brgit
sudo mv brgit /usr/local/bin/

For ARM architecture (Raspberry Pi, etc.), use brgit-linux-arm64

macOS

Intel Macs:

curl -L https://github.com/byterings/brgit/releases/latest/download/brgit-darwin-amd64 -o brgit
chmod +x brgit
sudo mv brgit /usr/local/bin/

Apple Silicon (M1/M2/M3):

curl -L https://github.com/byterings/brgit/releases/latest/download/brgit-darwin-arm64 -o brgit
chmod +x brgit
sudo mv brgit /usr/local/bin/

Windows

Run this command in PowerShell:

irm https://raw.githubusercontent.com/byterings/brgit/master/install.ps1 | iex

Verify Installation

brgit --version

You should see the version number printed

Getting Started

Initialize brgit

brgit init

This sets up brgit on your system and creates the necessary configuration directory at ~/.brgit/

Add your first identity

brgit add

This launches an interactive wizard that will ask for alias, name, email, GitHub username, and SSH key setup.

Add more identities

brgit add

Repeat the command to add your other accounts (personal, clients, etc.)

Switch between identities

brgit use work

All subsequent Git operations will use the selected identity. Your global .gitconfig and SSH configuration are updated automatically.

Usage Guide

Switching Identities

brgit use personal

Changes your active Git identity. All future commits will use this identity's name, email, and SSH key.

Viewing All Identities

brgit list

Shows all configured identities. The currently active identity is marked with a → symbol.

Checking Active Identity

brgit active

Shows which identity is currently active with full details.

Cloning Repositories

brgit clone https://github.com/org/repo.git

Clones a repository using the active identity's SSH config. Accepts any GitHub URL format.

Fix Repository Remote

brgit remote fix

Converts current repo's remote URL to use active identity's SSH config. Run inside a git repo.

Validating Configuration

brgit sync --fix

Validates that your Git and SSH configurations are correct. Use --fix to automatically correct any issues.

Removing an Identity

brgit delete work

Removes an identity from brgit. Optionally deletes SSH keys.

Updating SSH Keys

brgit update work --ssh-key ~/.ssh/new_key

Updates the SSH key for an existing identity. Useful for adding a key to a user created without one.

Tip: Cloning Made Easy

Use brgit clone to automatically clone with the correct SSH config:

brgit clone https://github.com/org/repo.git

This works with any GitHub URL format. brgit converts it to use the active identity's SSH key automatically.

Pro Tip: After switching identities with brgit use, you can continue using regular git commands as normal. brgit only manages your configuration—it doesn't wrap or replace git.

Workspaces

Workspaces let you organize projects by identity. Clone repos inside a workspace folder and brgit automatically uses the correct identity.

Create Workspaces

cd ~/projects
brgit workspace

# Creates folders for each identity:
#   ~/projects/work/      → uses "work" identity
#   ~/projects/personal/  → uses "personal" identity

Clone Inside Workspace

cd ~/projects/work
brgit clone https://github.com/company/repo.git
# Uses "work" identity automatically!

cd ~/projects/personal
brgit clone https://github.com/me/hobby.git
# Uses "personal" identity automatically!

Bind Individual Repos

For repos not in a workspace, bind them to an identity:

cd existing-repo
brgit bind --user work

# This repo now always uses "work" identity

Benefit: No need to remember to switch identities. Just work in the right folder and brgit handles the rest.

Identity Resolution

brgit determines which identity to use based on your current location:

Workspace

If inside a workspace folder, use that workspace's identity

Binding

If the repo has an explicit binding, use the bound identity

Global

Otherwise, use the global active user from brgit use

Check Current Resolution

brgit status

Shows which identity will be used and why (workspace, binding, or global).

Configuration

Configuration Files

brgit stores all configuration in ~/.brgit/config.toml. This file contains:

All your configured identities
Currently active identity
SSH key paths and Git configuration for each identity

SSH Keys

By default, brgit generates Ed25519 SSH keys in ~/.ssh/ with names like:

~/.ssh/brgit_work
~/.ssh/brgit_personal

You can also use existing SSH keys during the brgit add process.

Git Configuration

brgit modifies your global Git configuration (~/.gitconfig) to update:

user.name
user.email

All other Git settings remain unchanged.

Troubleshooting

Quick Fix: Run Doctor

For most issues, start with the doctor command:

brgit doctor --fix

This checks config, SSH permissions, and can auto-fix common problems.

SSH authentication fails

Run diagnostics with network check:

brgit doctor --network

If your key isn't on GitHub, copy it and add to GitHub Settings → SSH keys:

cat ~/.ssh/brgit_work.pub

Wrong identity being used

Check which identity is active and why:

brgit status

If you're in a workspace or bound repo, that identity takes precedence.

SSH permission errors

SSH requires specific permissions. Auto-fix with:

brgit doctor --fix

This sets ~/.ssh to 700 and key files to 600.

Command not found

Make sure brgit is in your PATH:

which brgit

If nothing is returned, reinstall following the installation instructions.

Still having issues? Report an issue on GitHub

Frequently Asked Questions

No. brgit only manages your Git and SSH configuration. You continue using regular git commands after switching identities.

Workspaces apply to all repos in a folder (created with 'brgit workspace'). Bindings apply to individual repos ('brgit bind'). Workspace takes priority over binding.

Run 'brgit status' to see the effective identity and why (workspace, binding, or global).

Yes! While brgit is optimized for GitHub, the Git configuration changes work with any Git hosting service.

Yes. brgit only modifies user.name and user.email. All other settings are preserved.

Run 'brgit doctor --fix' to automatically set correct permissions (700 for ~/.ssh, 600 for key files).

Run 'brgit uninstall' to safely restore all repositories to standard GitHub format and remove brgit config. Then remove the binary: sudo rm /usr/local/bin/brgit

Next Steps

Explore the full command reference or get help from the community

View All Commands Get Help