Documentation

Complete guide to using bgit for managing multiple Git identities

On This Page

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/master/install.ps1 | iex

Verify Installation

bgit --version

You should see the version number printed

Getting Started

1

Initialize bgit

bgit init

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

2

Add your first identity

bgit add

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

3

Add more identities

bgit add

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

4

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.

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

SSH authentication fails

Make sure you've added your public SSH key to GitHub:

  1. Copy your public key:
cat ~/.ssh/bgit_work.pub
  1. Go to GitHub → Settings → SSH and GPG keys
  2. Click "New SSH key" and paste the public key

Wrong identity being used

Run the following to reset your configuration:

bgit sync --fix

Command not found

Make sure bgit is in your PATH. Try running:

which bgit

If nothing is returned, reinstall bgit 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.
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.
During bgit add, you can choose to use existing SSH keys instead of generating new ones.
Switch to the correct identity with 'bgit use <alias>', then run 'bgit remote fix' inside the repository to update the remote URL.
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 CommandsGet Help