セマンティック・バージョニングしたい（`commitizen`）

$ cz commit
$ cz changelog --increment
$ cz bump

commitizen（cz）はGitのコミットメッセージをテンプレート化し、セマンティック・バージョニング（semantic versioning）に基づいたバージョン管理を簡単にするツールです。

コミットメッセージを入力するだけで、ルールに沿った変更履歴（CHANGELOG）の生成やバージョンタグの自動作成ができます。

インストールしたい（`commitizen`）

pipxでインストール

$ pipx install commitizen
$ which cz
~/.local/bin/cz

commitizenはグローバルに使うCLIなので、 pipxで隔離してインストールするとよいです。

pipでインストール

$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install commitizen
$ which cz

プロジェクトで使う場合は、venvで作った仮想環境にインストールする方法でもよいです。

uvでインストール

$ uv add commitizen --dev

Poetryでインストール

$ poetry add commitizen --group dev

チームで開発する場合、プロジェクトに開発環境として含めておくと便利です。commitizenはツールとして使うだけなので、devグループに追加します。

注釈

同じ名前のnpmパッケージがありますが、まったく別のプロジェクトです。自分がどちらを使っているのか混乱しないようにしましょう。

初期化したい（`cz init`）

$ cd プロジェクト名
$ cz init

cz initコマンドでプロジェクトを初期化し、commitizenの設定ファイルを作成します。ターミナルに表示されるダイアログに従い、矢印キーで選択します。

設定ファイルの配置

Pythonパッケージを開発している場合は、pyproject.tomlに設定を追加する方法を推奨します。その他の場合は、.cz.tomlなど好みの形式を選択できます。

初期設定ファイルの例

生成された設定ファイルは以下のようになっています。

[tool.commitizen]
name = "cz_conventional_commits"
version = "0.0.1"
tag_format = "$version"

コミットしたい（`cz commit`）

$ git add ファイル名
$ cz commit

cz commit（短縮形：cz c）でコミットを作成します。通常のgit commitの代わりです。ファイルのステージングはいつもどおりgit addしてください。

プロンプトが表示されるので、聞かれた内容に沿って情報を選択・入力すると、セマンティック・バージョニングに対応したコミットメッセージが自動生成されます。

テンプレートの確認

cz info - コミットメッセージのテンプレートを表示
cz schema - 詳細なスキーマを表示
cz example - テンプレートの使用例を表示

変更ログしたい（`cz changelog`）

$ cz changelog

cz changelog（短縮形：cz ch）で、コミットログから自動的に変更ログ（CHANGELOG）を生成できます。

デフォルトではCHANGELOG.mdというファイル名で作成されます。すでに存在する場合は上書きされます。

変更ログのオプション

# 前回からの差分のみを追記
$ cz changelog --increment

# ファイルに保存せず、標準出力で確認
$ cz changelog --dry-run

# ファイル名を変更
$ cz changelog --file-name HISTORY.md

推奨される使い方

新しいバージョンをリリースするときは、--incrementオプションを使って前回からの変更分だけを追記するのが便利です。

バージョンアップしたい（`cz bump`）

$ cz bump --changelog --check-consistency

プログラムの開発にひと区切りついたら、cz bumpでバージョンアップします。

このコマンドは以下の処理を自動で行います：

コミット履歴をもとに、セマンティック・バージョニング（semver）に従ったバージョン番号を決定
設定ファイル内のバージョン番号を更新
Gitタグを作成
CHANGELOG.mdを更新（--changelogオプション使用時）
複数ファイルのバージョン番号を一括更新（設定済みの場合）

よく使うオプション

# CHANGELOG.md を更新して、バージョン番号の一貫性をチェック
$ cz bump --changelog --check-consistency

# 短縮形
$ cz bump -ch -cc

バージョンタイプを指定したい

通常、commitizenはコミット履歴から自動的にバージョンを決定しますが、明示的に指定することもできます：

# パッチ版をリリース（例：1.0.0 -> 1.0.1）
$ cz bump --increment PATCH

# マイナー版をリリース（例：1.0.0 -> 1.1.0）
$ cz bump --increment MINOR

# メジャー版をリリース（例：1.0.0 -> 2.0.0）
$ cz bump --increment MAJOR

# CHANGELOG も同時に更新
$ cz bump --increment PATCH --changelog

詳細なオプション一覧

オプション	短縮形	説明
`--changelog`	`-ch`	`CHANGELOG.md`を更新する
`--check-consistency`	`-cc`	バージョン番号の一貫性をチェック
`--increment MAJOR\|MINOR\|PATCH`		バージョンタイプを指定
`--dry-run`		実際には変更せず、どのような操作を行うか表示
`--no-verify`		pre-commitフックをスキップ

注釈

バージョンアップとCHANGELOGの管理は、バージョンアップを先に行い、その後CHANGELOGを整理するのが推奨されます。

バージョン番号を一元管理したい

プロジェクトの複数の場所にバージョン番号が散らばっていると、cz bumpで更新するたびに手動で修正する手間が増えます。 version_filesを設定することで、cz bump時にすべてのバージョン番号を一括更新できます。

設定方法

[tool.commitizen]
version = "0.1.0"
tag_format = "v$version"
version_files = [
    "pyproject.toml:version",
    "src/__init__.py:__version__",
    "docs/conf.py:version",
]

version_filesにファイルパス:変数名の形式で設定します。

Pythonプロジェクトでの慣例

バージョン番号を管理するファイル：

pyproject.toml - プロジェクト設定ファイル（推奨）
src/__init__.py - パッケージの__version__変数
src/__version__.py - バージョン専用ファイル

ドキュメント設定

Sphinxでドキュメントを作成している場合：

docs/conf.py:version - 通常のSphinx設定
docs/source/conf.py:version - --sepオプション使用時

複数のファイルにバージョン番号を定義している場合は、初期設定のときにまとめて追加しておくことをオススメします。

フックしたい（`commitizen`）

pre-commitフレームワークを使用することで、commitizenをGitフックとして自動実行できます。

repos:
- repo: https://github.com/commitizen-tools/commitizen
  rev: v3.29.0
  hooks:
  - id: commitizen
    stages:
    - commit-msg

stages: [commit-msg]を指定することで、コミットメッセージが保存されたあとに検証が実行されます。これにより、セマンティック・バージョニングに従わないコミットメッセージは自動的に拒否されます。

セマンティック・バージョニングしたい（commitizen）

インストールしたい（commitizen）

初期化したい（cz init）