|
1 | | -[pre-commit]: https://pre-commit.com/ |
2 | | -[commitizen]: https://commitizen-tools.github.io/commitizen/ |
| 1 | +[prek]: https://prek.j178.dev/ |
3 | 2 | [Conventional Commits]: https://www.conventionalcommits.org |
4 | 3 |
|
5 | 4 |
|
6 | 5 | # Commit Workflow |
7 | 6 |
|
8 | 7 | ## Pre-Commit Hooks |
9 | | -Pre-commit hooks are scripts that automatically run before a commit is finalized, serving as a quality checkpoint for code changes. `afterpython` uses [pre-commit] to manage these hooks. |
| 8 | +Pre-commit hooks are scripts that automatically run before a commit is finalized, serving as a quality checkpoint for code changes. `afterpython` uses [prek] (a faster drop-in replacement for `pre-commit`) to manage these hooks. |
10 | 9 |
|
11 | | -After running `ap init`, if you agreed to create a `.pre-commit-config.yaml` file, it will be located in the `afterpython/` folder with some default hooks. Since this configuration file is not at the project root, you need to run `ap pre-commit` (or `ap pc` for short) instead of the `pre-commit` command—it automatically uses the configuration in `afterpython/`. |
| 10 | +After running `ap init`, if you agreed to create a `.pre-commit-config.yaml` file, it will be located in the `afterpython/` folder with some default hooks. Since this configuration file is not at the project root, you need to run `ap prek` (or `ap pc` for short) instead of the `prek` command—it automatically uses the configuration in `afterpython/`. |
12 | 11 |
|
13 | 12 | ### Commands |
14 | | -- `ap pre-commit` (or `ap pc`) — equivalent to `pre-commit --config afterpython/.pre-commit-config.yaml` |
| 13 | +- `ap prek` (or `ap pc`) — equivalent to `prek --config afterpython/.pre-commit-config.yaml` |
15 | 14 |
|
16 | 15 |
|
17 | 16 | --- |
18 | | -## Commitizen |
19 | | -If you agreed to create a `cz.toml` file during `ap init`, `afterpython` will use [commitizen] to help you write clear, structured commit messages following the [Conventional Commits] specification. |
20 | | - |
21 | | -Since the `cz.toml` configuration file is located in `afterpython/` (not the project root), use `ap cz` instead of the standard `cz` command. |
| 17 | +## Commit Messages |
| 18 | +`afterpython` checks that your commit messages follow the [Conventional Commits] format, e.g. `feat: add new feature`, `fix(cli): resolve bug`. This is done by the `ap-commit` hook in `afterpython/.pre-commit-config.yaml`, so just use `git commit` as usual. |
22 | 19 |
|
23 | 20 | ### Writing Commit Messages |
24 | | -**Recommended:** Use `ap commit` to create commits. This command: |
25 | | -1. Runs pre-commit hooks on changed files to catch issues early |
26 | | -2. Guides you through an interactive prompt to write a properly formatted commit message |
27 | | -3. Provides flags to skip checks when needed |
28 | | - |
29 | | -**Alternative:** Use `git commit` directly if you're comfortable writing [Conventional Commits] format messages (e.g., `feat: add new feature`, `fix: resolve bug`). Your message must match the format enforced in `cz.toml` and pass pre-commit hook checks. |
30 | | - |
31 | | - |
32 | | -**Bypassing checks:** To commit without running any checks: |
33 | | -- `git commit --no-verify` — skip pre-commit hooks |
34 | | -- `git push --no-verify` — skip pre-push hooks |
35 | | - |
36 | | -### Commands |
37 | | -- `ap cz` (or `ap commitizen`) — equivalent to `cz --config afterpython/cz.toml` |
38 | | -- `ap commit` — wrapper around `cz commit` with additional features: |
39 | | - - `ap commit --no-cz` — skip commitizen checks in pre-commit hooks |
40 | | - - `ap commit --no-pc` — skip pre-commit checks before writing the commit message |
41 | | -- `git commit --no-verify` — skip all pre-commit hooks |
| 21 | +- `git commit` — when your editor opens, the format and the allowed commit types are listed above git's own comments. |
| 22 | +- `git commit -m "feat: add new feature"` — the message is checked the same way. |
| 23 | + |
| 24 | +The message title must look like `<type>(<scope>): <description>`, where `(<scope>)` is optional and `<type>` is one of the allowed commit types. Add `!` before `:` for breaking changes, e.g. `feat!: drop Python 3.11`. |
| 25 | +Messages created by git itself (e.g. merge, revert, `fixup!` and `squash!` commits) are let through as-is. |
| 26 | + |
| 27 | +If the message is rejected, it is saved, so you can edit and retry with the `git commit -e -F <file>` command shown in the error. |
| 28 | + |
| 29 | +### Commit Types |
| 30 | +Commit types can be defined in `afterpython/afterpython.toml` (`type = "description"`), `ap init` creates it with these defaults: |
| 31 | +```toml |
| 32 | +# allowed commit types, e.g. "feat: add X"; add or remove lines freely |
| 33 | +[commit.types] |
| 34 | +feat = "A new feature" |
| 35 | +fix = "A bug fix" |
| 36 | +docs = "Documentation only changes" |
| 37 | +style = "Formatting, no code meaning change" |
| 38 | +refactor = "Neither fixes a bug nor adds a feature" |
| 39 | +perf = "Performance improvement" |
| 40 | +test = "Adding or fixing tests" |
| 41 | +build = "Build system or dependencies" |
| 42 | +ci = "CI configuration" |
| 43 | +chore = "Other changes that don't modify src or tests" |
| 44 | +wip = "Work in progress" |
| 45 | +``` |
| 46 | +To allow a new type, add a line, e.g. `deps = "Dependency updates"`; to disallow one, remove its line. The descriptions are shown in the commit message template and in the error message when a commit is rejected. |
| 47 | + |
| 48 | +### Bypassing Checks |
| 49 | +- `SKIP=ap-commit git commit` — skip the commit message check |
| 50 | +- `git commit --no-verify` — skip all pre-commit and commit message hooks |
42 | 51 | - `git push --no-verify` — skip all pre-push hooks |
43 | | - |
44 | | - |
45 | | -:::{tip} Commitizen Customization |
46 | | -<!-- :class: dropdown --> |
47 | | -Customize the commit message format by editing `cz.toml`. |
48 | | - |
49 | | -See [Commitizen Customization](https://commitizen-tools.github.io/commitizen/customization/) for details. |
50 | | -::: |
|
0 commit comments