gitmask

No more wrong emails in your commits - automatically set git user info based on git remote domain.

Features

• Automatically detect git remote domain and set corresponding user.name and user.email
• Support multiple git remotes (GitHub, GitLab, self-hosted, etc.)
• Default user configuration for unmapped domains
• Git hook integration (pre-commit)
• Shell integration (fish, bash, zsh) for automatic config on directory change
• CLI for manual control
• JSON configuration file

Installation

Build from source (recommended)

git clone https://github.com/tsonglew/gitmask.git
cd gitmask
npm install
npm run build
npm link

Why build from source?

• Ensures you have all the required files
• Works with all npm versions
• No installation issues

Install from GitHub (experimental)

npm install -g tsonglew/gitmask

Note: This method may not work reliably in all environments. If you encounter issues, please use the build from source method above.

Try without installing (using npx)

npx tsonglew/gitmask --version
npx tsonglew/gitmask init
npx tsonglew/gitmask add github.com "Your Name" "[email protected]"

Use this if you want to try gitmask without installing it globally. Note that shell integration requires global installation.

Verify Installation (for build from source or npm install)

After installation, check if gitmask is available:

gitmask --version
# Should output: 1.0.0

If gitmask command is not found, continue with troubleshooting steps below.

Troubleshooting

Step 1: Check npm global bin location

npm config get prefix
# Example output: /usr/local/lib/node_modules
# or: /Users/yourname/.npm-global

Then the bin directory is: (npm config get prefix)/bin

Step 2: Check if gitmask binary exists

ls $(npm config get prefix)/bin/gitmask
# Should show: gitmask

If the file doesn't exist, the installation failed. Try reinstalling:

npm uninstall -g gitmask
npm install -g tsonglew/gitmask

Step 3: Add npm global bin to your PATH

If the binary exists but gitmask command is not found, your shell doesn't know where to find it. Add npm global bin to your PATH:

For fish:

fish_add_path $(npm config get prefix)/bin

For zsh:

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

For bash:

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Step 4: Verify again

gitmask --version

Build from source

git clone https://github.com/tsonglew/gitmask.git
cd gitmask
npm install
npm run build
npm link

Verify installation

gitmask --version
# Should output: 1.0.0

Quick start

After installation, follow these quick steps to get started:

# 1. Initialize the config
gitmask init

# 2. Add your GitHub account
gitmask add github.com "Your GitHub Name" "[email protected]"

# 3. Install shell integration (recommended)
gitmask install-shell

# 4. Restart your shell or reload config
# For fish: source ~/.config/fish/config.fish
# For zsh: source ~/.zshrc
# For bash: source ~/.bash_profile or source ~/.bashrc

Now whenever you cd into a git repository, gitmask will automatically set the correct git user info!

Usage

1. Initialize config

gitmask init

This creates ~/.config/gitmask/config.json configuration file.

2. Add domain mappings

gitmask add github.com "Your Name" "[email protected]"
gitmask add gitlab.com "Your Name" "[email protected]"
gitmask add github.company.com "Work Name" "[email protected]"

3. List all mappings

gitmask list

4. Check and set git user info

gitmask check

This command:

• Detects the current git remote
• Finds the matching user mapping
• Updates git config user.name and git config user.email if needed

5. Install git hook (optional)

gitmask install-hook

This installs a pre-commit hook that automatically checks and sets user info before each commit.

6. Install shell integration (optional, recommended)

gitmask install-shell

This installs shell integration that automatically checks and sets git user info when you enter a git repository. Supports fish, bash, and zsh.

After installation, restart your shell or run:

• fish: source ~/.config/fish/config.fish
• bash: source ~/.bash_profile or source ~/.bashrc
• zsh: source ~/.zshrc

7. Set default user (optional)

gitmask set-default "Default Name" "[email protected]"

This sets a default user that will be used when no domain mapping matches.

8. Clear default user

gitmask clear-default

9. Remove a mapping

gitmask remove github.com

10. Uninstall git hook

gitmask uninstall-hook

11. Uninstall shell integration

gitmask uninstall-shell

Configuration

The configuration file is stored at ~/.config/gitmask/config.json:

{
  "mappings": [
    {
      "domain": "github.com",
      "user": {
        "name": "Your GitHub Name",
        "email": "[email protected]"
      }
    },
    {
      "domain": "gitlab.com",
      "user": {
        "name": "Your GitLab Name",
        "email": "[email protected]"
      }
    }
  ],
  "default": {
    "name": "Default Name",
    "email": "[email protected]"
  }
}

The default field is optional. When specified, it will be used when no domain mapping matches the current git remote.

How it works

1. Gitmask reads the current git repository's remote URL
2. Extracts the domain from the remote URL
3. Looks up the domain in the configuration file
4. If a matching domain is found, uses its user info; otherwise, falls back to the default user (if configured)
5. Sets user.name and user.email for the current repository

Supported remote formats

• HTTPS: https://github.com/user/repo.git
• SSH: [email protected]:user/repo.git
• Custom domains: https://github.company.com/user/repo.git

License

MIT