Documentation

Complete guide to using the bgit CLI tool for managing multiple Git identities

Installation

Linux

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

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

macOS

Intel Macs:

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

Apple Silicon (M1/M2/M3):

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

Windows

Run this command in PowerShell:

irm https://raw.githubusercontent.com/byterings/bgit/main/install.ps1 | iex

Verify Installation

bgit --version

You should see the version number printed

Getting Started

Initialize bgit

bgit init

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

Add your first identity

bgit add

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

Add more identities

bgit add

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

Switch between identities

bgit use work

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

Usage Guide

Switching Identities

bgit use personal

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

Viewing All Identities

bgit list

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

Checking Active Identity

bgit active

Shows which identity is currently active with full details.

Cloning Repositories

bgit 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

bgit remote fix

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

Validating Configuration

bgit sync --fix

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

Removing an Identity

bgit delete work

Removes an identity from bgit. Optionally deletes SSH keys.

Updating SSH Keys

bgit 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 bgit clone to automatically clone with the correct SSH config:

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

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

Pro Tip: After switching identities with bgit use, you can continue using regular git commands as normal. bgit 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 bgit automatically uses the correct identity.

Create Workspaces

cd ~/projects
bgit workspace

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

Clone Inside Workspace

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

cd ~/projects/personal
bgit 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
bgit 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 bgit handles the rest.

Identity Resolution

bgit 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 bgit use

Check Current Resolution

bgit status

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

Configuration

Configuration Files

bgit stores all configuration in ~/.bgit/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, bgit generates Ed25519 SSH keys in ~/.ssh/ with names like:

~/.ssh/bgit_work
~/.ssh/bgit_personal

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

Git Configuration

bgit 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:

bgit doctor --fix

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

SSH authentication fails

Run diagnostics with network check:

bgit doctor --network

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

cat ~/.ssh/bgit_work.pub

Wrong identity being used

Check which identity is active and why:

bgit status

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

SSH permission errors

SSH requires specific permissions. Auto-fix with:

bgit doctor --fix

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

Command not found

Make sure bgit is in your PATH:

which bgit

If nothing is returned, reinstall following the installation instructions.

Still having issues? Report an issue on GitHub

Frequently Asked Questions

No. bgit 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 'bgit workspace'). Bindings apply to individual repos ('bgit bind'). Workspace takes priority over binding.

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

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

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

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

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

Next Steps

Explore the full command reference or get help from the community

View All Commands Get Help