Metadata-Version: 2.4
Name: git-profiles
Version: 0.3.0
Summary: CLI tool to manage multiple Git configuration profiles
Keywords: git,cli,profiles,configuration,developer,tools
Author: Niklas Kaaf
Author-email: Niklas Kaaf <nkaaf@protonmail.com>
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Dist: filelock==3.29.7
Requires-Dist: platformdirs==4.10.0
Requires-Dist: pydantic==2.13.4
Requires-Dist: typing-extensions==4.16.0
Maintainer: Niklas Kaaf
Maintainer-email: Niklas Kaaf <nkaaf@protonmail.com>
Requires-Python: >=3.10, <3.15
Project-URL: homepage, https://github.com/nkaaf/git-profiles
Project-URL: issues, https://github.com/nkaaf/git-profiles/issues
Project-URL: source, https://github.com/nkaaf/git-profiles
Description-Content-Type: text/markdown

# git-profiles

[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/nkaaf/git-profiles/main.svg)](https://results.pre-commit.ci/latest/github/nkaaf/git-profiles/main)
![PyPI - Status](https://img.shields.io/pypi/status/git-profiles)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/git-profiles?logo=python)
![PyPI - License](https://img.shields.io/pypi/l/git-profiles)
![Codecov](https://img.shields.io/codecov/c/github/nkaaf/git-profiles?logo=codecov&logoColor=%23b&link=https%3A%2F%2Fcodecov.io%2Fgh%2Fnkaaf%2Fgit-profiles)

![PyPI - Version](https://img.shields.io/pypi/v/git-profiles?logo=pypi&link=https%3A%2F%2Fpypi.org%2Fproject%2Fgit-profiles%2F)

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:

```bash
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:

```bash
# 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)

```bash
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`:

```bash
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):**

```bash
git-profiles <command>
```

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

```bash
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):**

```bash
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

```bash
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

```bash
git-profiles unset work user.email

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

### Apply a profile to the local Git repository

```bash
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

```bash
git-profiles list

# Git alias equivalent:
git profiles list
```

### Show all key-values of a profile

```bash
git-profiles show work

# Git alias equivalent:
git profiles show work
```

### Remove an entire profile

```bash
git-profiles remove work

# Git alias equivalent:
git profiles remove work
```

### Duplicate a profile

```bash
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.

```bash
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:

```bash
# 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

```bash
# 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

```bash
# 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:

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

# Build both wheel and source distribution
uv build
```
