Metadata-Version: 2.4
Name: cz-path
Version: 0.0.7
Summary: Commitizen plugin that prefixes commit messages with the common path or prefix of staged files.
Project-URL: Issues, https://github.com/Tatsh/cz-path/issues
Project-URL: documentation, https://cz-path.readthedocs.org
Project-URL: homepage, https://tatsh.github.io/cz-path/
Project-URL: repository, https://github.com/Tatsh/cz-path
Author-email: Andrew Udvare <audvare@gmail.com>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: commit messages,commitizen,git,version control
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
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: Typing :: Typed
Requires-Python: <4.0,>=3.10
Requires-Dist: commitizen>=4.13.10
Requires-Dist: gitpython>=3.1.46
Requires-Dist: typing-extensions>=4.15.0
Description-Content-Type: text/markdown

# cz-path

<!-- WISWA-GENERATED-README:START -->

[![Python versions](https://img.shields.io/pypi/pyversions/cz-path.svg?color=blue&logo=python&logoColor=white)](https://www.python.org/)
[![PyPI - Version](https://img.shields.io/pypi/v/cz-path)](https://pypi.org/project/cz-path/)
[![GitHub tag (with filter)](https://img.shields.io/github/v/tag/Tatsh/cz-path)](https://github.com/Tatsh/cz-path/tags)
[![License](https://img.shields.io/github/license/Tatsh/cz-path)](https://github.com/Tatsh/cz-path/blob/master/LICENSE.txt)
[![GitHub commits since latest release (by SemVer including pre-releases)](https://img.shields.io/github/commits-since/Tatsh/cz-path/v0.0.7/master)](https://github.com/Tatsh/cz-path/compare/v0.0.7...master)
[![CodeQL](https://github.com/Tatsh/cz-path/actions/workflows/codeql.yml/badge.svg)](https://github.com/Tatsh/cz-path/actions/workflows/codeql.yml)
[![QA](https://github.com/Tatsh/cz-path/actions/workflows/qa.yml/badge.svg)](https://github.com/Tatsh/cz-path/actions/workflows/qa.yml)
[![Tests](https://github.com/Tatsh/cz-path/actions/workflows/tests.yml/badge.svg)](https://github.com/Tatsh/cz-path/actions/workflows/tests.yml)
[![Coverage Status](https://coveralls.io/repos/github/Tatsh/cz-path/badge.svg?branch=master)](https://coveralls.io/github/Tatsh/cz-path?branch=master)
[![Dependabot](https://img.shields.io/badge/Dependabot-enabled-blue?logo=dependabot)](https://github.com/dependabot)
[![Documentation Status](https://readthedocs.org/projects/cz-path/badge/?version=latest)](https://cz-path.readthedocs.org/?badge=latest)
[![mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
[![uv](https://img.shields.io/badge/uv-261230?logo=astral)](https://docs.astral.sh/uv/)
[![pytest](https://img.shields.io/badge/pytest-zz?logo=Pytest&labelColor=black&color=black)](https://docs.pytest.org/en/stable/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Downloads](https://static.pepy.tech/badge/cz-path/month)](https://pepy.tech/project/cz-path)
[![Stargazers](https://img.shields.io/github/stars/Tatsh/cz-path?logo=github&style=flat)](https://github.com/Tatsh/cz-path/stargazers)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
[![Prettier](https://img.shields.io/badge/Prettier-black?logo=prettier)](https://prettier.io/)

[![@Tatsh](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpublic.api.bsky.app%2Fxrpc%2Fapp.bsky.actor.getProfile%2F%3Factor=did%3Aplc%3Auq42idtvuccnmtl57nsucz72&query=%24.followersCount&label=Follow+%40Tatsh&logo=bluesky&style=social)](https://bsky.app/profile/Tatsh.bsky.social)
[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Tatsh-black?logo=buymeacoffee)](https://buymeacoffee.com/Tatsh)
[![Libera.Chat](https://img.shields.io/badge/Libera.Chat-Tatsh-black?logo=liberadotchat)](irc://irc.libera.chat/Tatsh)
[![Mastodon Follow](https://img.shields.io/mastodon/follow/109370961877277568?domain=hostux.social&style=social)](https://hostux.social/@Tatsh)
[![Patreon](https://img.shields.io/badge/Patreon-Tatsh2-F96854?logo=patreon)](https://www.patreon.com/Tatsh2)

<!-- WISWA-GENERATED-README:STOP -->

Commitizen plugin that prefixes commit messages with the common path or prefix of staged files.

## Installation

```shell
pip install cz-path
```

The package depends on Commitizen, so you get the `cz` command when you install `cz-path`.

## Usage

### Configure Commitizen

Point Commitizen at this plugin by setting `name` to `cz_path` in your configuration file (see
below). To use this plugin for a single run without changing the config file, pass `-n cz_path` or
`--name cz_path` to `cz`.

### Create a commit

1. **Use a Git repository.** Run `cz` from the repository root. The plugin opens the Git index in
   the current directory, so running it elsewhere will not see your project.

2. **Stage your changes** with `git add`. The plugin looks at the staged diff against `HEAD` to
   suggest a path prefix. If nothing is staged, Commitizen fails with a message that no staged files
   were found.

3. **Start Commitizen** to write the message and create the commit:

   ```shell
   cz commit
   ```

   Short form: `cz c`.

4. **Answer the prompts:**
   - **Prefix** — pick the suggested path prefix (if shown), or `project`, or `(empty)` for no
     prefix.
   - **Commit title** — the rest of the subject line. The full message is `<prefix>: <title>`.

### Message format

Commits follow `<prefix>: <title>`, for example `module/component: short description of the change`.
The pattern is a prefix (which may be empty), then a colon and space, then the title.

By default, `src/` is stripped from the computed prefix. Set `remove_path_prefixes` to `[]` to turn
that off, or add other path segments (such as a top-level package name) to strip. You do not need to
include a trailing `/` in each entry.

### `pyproject.toml`

```toml
[tool.commitizen]
name = "cz_path"
remove_path_prefixes = ["src", "module_name"]
```

### `.cz.json`

```json
{
  "commitizen": {
    "name": "cz_path",
    "remove_path_prefixes": ["src", "module_name"]
  }
}
```

### Scenarios

| Staged files           | Path prefix | String prefix |
| ---------------------- | ----------- | ------------- |
| `src/a.c`, `src/b.c`   | `src`       | `src/`        |
| `src/a1.c`, `src/a2.c` | `src`       | `src/a`       |
| `a.c`, `b.c`           | (no option) | (no option)   |

If no prefix is found amongst the staged files, only the choices `project` and empty will be given.
