Commands Reference

Complete reference for all brgit commands

Commands

Detailed Documentation

brgit init

Initialize brgit on your system

Usage

brgit init

Details

Sets up brgit configuration directory at ~/.brgit/ and prepares the system for managing multiple Git identities. Optional - brgit auto-initializes on first use.

brgit add

Add a new Git identity

Usage

brgit add
brgit add --alias work --name "John Doe" --email "john@work.com" --github "john-work"

Details

Launches an interactive wizard to configure a new identity. You'll be prompted for alias, name, email, GitHub username, and SSH key setup. You can also provide flags directly to skip prompts. Use --ssh-key to specify an existing SSH key path.

brgit list

List all configured identities

Usage

brgit list
brgit ls

Details

Displays all identities you've configured. The currently active identity is marked with a → symbol. You can also use the short alias "ls".

brgit use

Switch to a different identity

Usage

brgit use <alias>
brgit use -u <github-username>
brgit use -m <email>

Details

Switches your Git configuration to use the specified identity. Updates your global .gitconfig and SSH configuration. You can switch by alias (default), GitHub username (-u), or email (-m). On Windows, automatically starts SSH agent and loads keys.

Example

brgit use work

brgit active

Show the currently active identity

Usage

brgit active

Details

Displays which identity is currently being used for Git operations, including name, email, GitHub username, and SSH key path.

brgit clone

Clone a repository with correct SSH config

Usage

brgit clone <url> [directory]

Details

Clones a GitHub repository using the active user's SSH configuration. Accepts any GitHub URL format (HTTPS or SSH) and automatically converts it to use the correct SSH key for the active identity.

Example

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

brgit remote fix

Fix repository remote URL for active identity

Usage

brgit remote fix

Details

Converts the current repository's origin remote URL to use the active user's SSH config. Run this inside a git repository after switching identities to fix authentication issues.

brgit remote restore

Restore remote URL to standard GitHub format

Usage

brgit remote restore

Details

Converts the current repository's origin remote URL back to standard GitHub format. Useful before uninstalling brgit or when you want to revert to normal git@github.com URLs.

brgit sync

Validate and fix Git/SSH configuration

Usage

brgit sync
brgit sync --fix

Details

Checks that your Git and SSH configurations match the active identity. Validates user.name, user.email, SSH key existence, and file permissions. Use --fix flag to automatically correct any issues.

Example

brgit sync --fix

brgit workspace

Create workspace folders with automatic identity binding

Usage

brgit workspace
brgit workspace --path ~/code
brgit workspace --users work,personal
brgit workspace --list
brgit workspace --remove work

Details

Creates organized workspace directories for each identity. All repositories cloned within a workspace folder automatically use that identity, regardless of the global active user. Use --list to view configured workspaces, --remove to delete a workspace binding.

Example

brgit workspace --path ~/projects

brgit bind

Bind current repository to a specific identity

Usage

brgit bind
brgit bind --user work
brgit bind --force
brgit bind --remove

Details

Binds the current repository to a specific identity. The binding persists regardless of the global active user. Use --user to specify identity, --force to override existing binding, --remove to unbind.

Example

brgit bind --user work

brgit status

Show current identity status and bindings

Usage

brgit status

Details

Displays comprehensive identity status including: active global identity, current location, effective identity (workspace/binding/global), configured workspaces, and repository bindings. Helps understand which identity will be used for the current context.

brgit doctor

Diagnose and fix configuration issues

Usage

brgit doctor
brgit doctor --network
brgit doctor --fix

Details

Runs comprehensive diagnostics on your brgit setup. Checks config validity, SSH directory/key permissions (700/600), SSH agent status, git config, and optionally network connectivity to GitHub. Use --fix to automatically correct permission issues.

Example

brgit doctor --fix

brgit delete

Remove an identity

Usage

brgit delete <alias>

Details

Removes an identity from brgit. Confirms before deletion and optionally deletes SSH key files. Clears active user if deleted identity was active.

Example

brgit delete old-work

brgit update

Update an identity's SSH key

Usage

brgit update <alias> --ssh-key <path>

Details

Updates the SSH key for an existing identity. Useful for adding a key to a user created without one, or changing to a new key. Automatically updates SSH config.

Example

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

brgit setup-ssh

Setup SSH agent and load keys

Usage

brgit setup-ssh

Details

Sets up SSH agent and loads SSH keys for all configured identities. On Windows, starts the SSH agent service and sets it to automatic startup. On Linux/macOS, provides instructions if SSH agent isn't running.

brgit uninstall

Safely uninstall brgit

Usage

brgit uninstall
brgit uninstall --force
brgit uninstall --skip-repos

Details

Safely uninstalls brgit by scanning for repositories with brgit remote URLs and restoring them to standard GitHub format. Removes brgit SSH config entries and configuration directory. Use --skip-repos to skip repository scanning, --force to skip confirmation.

brgit --version

Show brgit version

Usage

brgit --version

Details

Displays the current version of brgit.

brgit help

Show help information

Usage

brgit help
brgit <command> --help

Details

Displays help information and available commands. Use --help with any command to see its specific options.

Common Workflows

First Time Setup

# Add your work account
brgit add

# Add your personal account
brgit add

# List all identities
brgit list

Using Workspaces

# Create workspace folders
cd ~/projects
brgit workspace

# Clone in workspace - auto identity!
cd ~/projects/work
brgit clone https://github.com/company/repo.git

Troubleshooting

# Run diagnostics
brgit doctor

# Auto-fix permission issues
brgit doctor --fix

# Check current status
brgit status

Bind Existing Repo

# Bind repo to identity
cd my-project
brgit bind --user work

# Fix remote URL
brgit remote fix

# Now git push/pull works!

Tip: Use brgit clone

The easiest way to clone is with brgit clone which automatically uses the correct SSH config:

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

Alternatively, you can use identity-specific hostname format manually: git@github.com-work:org/repo.git

Pro Tips

•Use brgit workspace to auto-switch identity by folder
•Run brgit doctor when SSH authentication fails
•Use brgit status to see which identity will be used
•Bind repos with brgit bind for sticky identity

Need more help? Check out the full documentation or ask the community

Read Documentation Ask a Question