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.
- 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.
⚠️ Note: The recommended method is via pipx. Ifpipxis not installed, you can fall back topipor other methods below.
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-profilesIf 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-profilesbrew install nkaaf/tap/git-profiles⚡ Makes
git-profilesglobally available. Recommended if you already manage packages with Homebrew.
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
uvis installed; it manages dependencies and project commands.
After installation (via pipx, pip, Homebrew, or the development workflow), you can use
git-profiles in three ways:
- Global CLI (recommended fallback):
git-profiles <command>- 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.
- Python module (for development or scripting):
python3 -m git_profiles <command>💡 Examples below will show both the global CLI and Git alias variants.
git-profiles set work user.name "Alice Example"
git-profiles set work user.email "[email protected]"
# Git alias equivalent:
git profiles set work user.name "Alice Example"
git profiles set work user.email "[email protected]"git-profiles unset work user.email
# Git alias equivalent:
git profiles unset work user.emailgit-profiles apply work
# Git alias equivalent:
git profiles apply workThis sets all the keys in the work profile for the current repository.
git-profiles list
# Git alias equivalent:
git profiles listgit-profiles show work
# Git alias equivalent:
git profiles show workgit-profiles remove work
# Git alias equivalent:
git profiles remove workgit-profiles duplicate work personal
# Git alias equivalent:
git profiles duplicate work personalCreates a copy of the work profile named personal.
-q,--quiet: Suppress normal output. Errors are still shown.
git-profiles -q apply work
# Git alias equivalent:
git profiles -q apply work💡 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 (pytest, tox, ruff, pre-commit, etc.)
uv sync
# 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 viauv run poe <script>(e.g.,uv run poe lint,uv run poe test). This ensures the correct uv-managed environment is used. Runningpoeortoxdirectly may fail if the environment isn’t active, especially on CI runners.
# Run all linting checks
uv run poe lintℹ️ This internally runs
pre-commitusing the uv-managed environment. 💡 Commits automatically trigger pre-commit hooks afterpre-commit install. If any hook fails (e.g., lint errors), the commit is blocked until fixed.
# Run all test environments defined in pyproject.toml
uv run poe testℹ️ This internally runs
toxusing the uv-managed environment.⚠️ Note: Tox requires the Python interpreters listed in[tool.tox].envlist. With thetox-uvplugin, missing interpreters are installed automatically. You can also install specific Python versions manually withuv python install <version>.
You can build the git-profiles package locally for testing or distribution:
# Ensure your development environment is synced
uv sync
# Build both wheel and source distribution
uv build⚡ Using
uv syncensures that all development dependencies are available during the build process.
For more information on the tools used in this project, you can visit their official documentation:
- uv – Dependency manager for Python projects, used here to manage dev dependencies and Python interpreters.
- tox – Automate testing across multiple Python versions.
- pre-commit – Manage and run pre-commit hooks to ensure code quality.
- Poe the Poet – Task runner that simplifies running
scripts (like
lintandtest) defined inpyproject.toml. - pipx – Install and run Python CLI tools in isolated environments while making them available globally.
- Python Packaging Guide – Official guide for building, packaging, and distributing Python projects, including creating source distributions and wheels.
- Homebrew – Popular package manager for macOS and Linux, used to install CLI tools and dependencies system-wide.
💡 These links provide detailed documentation, installation guides, and examples for each tool. They’re especially useful if you’re new to Python project tooling.
The repository’s CI pipelines automatically run:
- Tests across all Python versions defined in
[tool.tox].envlist - Pre-commit hooks for linting and code quality
✅ This ensures that every commit and pull request is tested and checked consistently with your local development setup.
Apache License 2.0 – see LICENSE for details.
This project depends on the following open source libraries:
- platformdirs — MIT License
- pydantic — MIT License