git-profiles

A CLI tool to manage multiple Git configuration profiles, allowing developers to switch between different identities and settings quickly. Profiles are stored persistently and can be applied to local Git repositories with ease.

Features

• Create, update, and delete Git config profiles.
• Set and unset key-value pairs in profiles (user.name, user.email, etc.).
• Apply a profile to the local Git repository.
• Duplicate existing profiles.
• List all available profiles and show profile contents.
• Cross-platform persistent storage using platformdirs.
• Input validation for safe keys and valid emails.
• Quiet mode for scripting or automation.

Installation

⚠️ Note: The recommended method is via pipx. If pipx is not installed, you can fall back to pip or other methods below.

1️⃣ Recommended: Install via pipx (isolated and global CLI)

pipx installs Python CLI tools in isolated environments while making them available system-wide. This prevents conflicts with other Python packages and keeps your environment clean:

pipx install git-profiles

2️⃣ Alternative: Install via pip (inside a virtual environment recommended)

If pipx is not available, you can use pip. It is recommended to install inside a virtual environment to avoid polluting your global Python packages:

# Optional: create a virtual environment
python3 -m venv ~/.venvs/git-profiles
source ~/.venvs/git-profiles/bin/activate

# Install the package
pip install git-profiles

3️⃣ Alternative: Install via Homebrew (macOS / Linux)

brew install nkaaf/tap/git-profiles

⚡ Makes git-profiles globally available. Recommended if you already manage packages with Homebrew.

4️⃣ Development Installation (Editable / Contributing)

Clone the repository and install in editable mode using uv:

git clone https://github.com/nkaaf/git-profiles.git
cd git-profiles

# Ensure dependencies match the lockfile
uv sync

⚡ This allows you to modify the source code while testing. Make sure uv is installed; it manages dependencies and project commands.

Usage

After installation (via pipx, pip, Homebrew, or the development workflow), you can use git-profiles in three ways:

1. Global CLI (recommended fallback):

git-profiles <command>

2. Git alias (preferred and automatically available if Git is installed):

git profiles <command>

💡 Tip: The Git alias integrates seamlessly with your workflow and is the most convenient way to run commands.

3. Python module (for development or scripting):

python3 -m git_profiles <command>

💡 Examples below will show both the global CLI and Git alias variants.

Set a key-value pair in a profile

git-profiles set work user.name "Alice Example"
git-profiles set work user.email "alice@example.com"

# Git alias equivalent:
git profiles set work user.name "Alice Example"
git profiles set work user.email "alice@example.com"

Remove a key from a profile

git-profiles unset work user.email

# Git alias equivalent:
git profiles unset work user.email

Apply a profile to the local Git repository

git-profiles apply work

# Git alias equivalent:
git profiles apply work

This sets all the keys in the work profile for the current repository.

List all available profiles

git-profiles list

# Git alias equivalent:
git profiles list

Show all key-values of a profile

git-profiles show work

# Git alias equivalent:
git profiles show work

Remove an entire profile

git-profiles remove work

# Git alias equivalent:
git profiles remove work

Duplicate a profile

git-profiles duplicate work personal

# Git alias equivalent:
git profiles duplicate work personal

Creates a copy of the work profile named personal.

Options

• -q, --quiet: Suppress normal output. Errors are still shown.

git-profiles -q apply work

# Git alias equivalent:
git profiles -q apply work

Development

💡 Prerequisite: Make sure you have uv installed on your system. It is the dependency manager used to install dev dependencies, manage Python interpreters, and run project commands.

Get your development environment ready in a few steps:

# 1. Install all development dependencies
uv sync --frozen

# 2. Install pre-commit git hooks
pre-commit install

💡 After this, your environment is ready to run tests, linting, and builds.

⚠️ Important: Always run commands via uv run poe <script> (e.g., uv run poe lint, uv run poe test). This ensures the correct uv-managed environment is used. Running poe directly may fail if the environment isn’t active, especially on CI runners.

Linting

# Run all linting checks
uv run poe lint

ℹ️ This internally runs pre-commit using the uv-managed environment.

💡 Commits automatically trigger pre-commit hooks after pre-commit install. If any hook fails (e.g., lint errors), the commit is blocked until fixed.

Testing

# Run all tests defined in pyproject.toml
uv run poe test

ℹ️ This internally runs pytest using the uv-managed environment. You can also run specific python tests with uv run poe test-<version>.

Building

You can build the git-profiles package locally for testing or distribution:

# Ensure your environment is synced
uv sync --frozen --group build --no-dev

# Build both wheel and source distribution
uv build