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

$ cz version
4.17.1

$ cz commit
$ cz changelog --incremental
$ cz bump

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

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

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

• pipでインストール

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

• pipxでインストール

$ pipx install commitizen

• uv toolでインストール

$ uv tool install commitizen

• uvでプロジェクトに追加

$ uv add commitizen --group dev

• poetryでプロジェクトに追加

$ poetry add commitizen --group dev

注釈

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

設定したい（[tool.commitizen]）

[tool.commitizen]
name = "cz_conventional_commits"
version = "0.1.0"
tag_format = "v$version"
version_scheme = "semver2"
version_provider = "uv"
update_changelog_on_bump = true
major_version_zero = true
version_files = [
    "pyproject.toml:version",
    "src/__init__.py:__version__",
    "docs/conf.py:version",
]

commitizenの設定は、pyproject.tomlの[tool.commitizen]セクションに書きます。 nameでコミットメッセージのルール（テンプレート）を指定します。 versionで現在のバージョン番号、tag_formatでGitタグの命名規則を指定します。 $versionの部分がバージョン番号に置き換わります。 update_changelog_on_bumpとmajor_version_zeroについては、 このあとの「初期化したい」のダイアログとあわせて後述します。

version_filesで、バージョン番号を書き換えたい他のファイルを指定できます。 ファイルパス:変数名の形式で書きます。 プロジェクトの複数の場所にバージョン番号が散らばっていると、 更新するたびに手動で修正する手間が増えますが、 version_filesを設定しておけば、cz bump実行時にまとめて一括更新できます。

Pythonプロジェクトでよく指定されるファイルの例：

• pyproject.toml:version - プロジェクト設定ファイル（推奨）

• src/__init__.py:__version__ - パッケージの__version__変数

• docs/conf.py:version - Sphinxドキュメントの設定ファイル

• docs/source/conf.py:version - sphinx-quickstart --sepでソースとビルドを分けた場合

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

スキーマしたい（version_scheme）

[tool.commitizen]
version_scheme = "semver2"

version_schemeで、バージョン番号の表記形式を指定できます。

• semver - Semantic Versioning（例：1.0.0-beta.1）

• semver2 - semverと互換性のある形式（デフォルト、例：1.0.0-beta.1）

• pep440 - Pythonパッケージング標準のPEP 440形式（例：1.0.0b1）

同じプレリリースバージョンでも、スキームによって表記が変わります。 semver2では1.0.0-beta.1のままですが、pep440では1.0.0b1に正規化されます。 PyPIに公開するPythonパッケージであればpep440が適しています。

プロバイダーしたい（version_provider）

[tool.commitizen]
version_provider = "pep621"

version_providerで、バージョン番号の読み書き先を指定できます。 指定すると、[tool.commitizen]のversionキー自体は省略できます。

値	読み書き先
commitizen（デフォルト）	[tool.commitizen]のversion
pep621	pyproject.tomlの[project]のversion
uv	pyproject.tomlの[project]のversionとuv.lock
poetry	pyproject.tomlの[tool.poetry]のversion
cargo	Cargo.tomlの[project]のversion
npm	package.jsonのversion
composer	composer.jsonのversion
scm	Gitから取得（バージョンの書き戻しはしない）

uvでプロジェクトを管理している場合は"uv"、 それ以外のPythonプロジェクトでは"pep621"を指定するのがオススメです。 cz init実行時のダイアログでもpep621が推奨として案内されます。

初期化したい（cz init）

$ cd プロジェクト名
$ cz init
Welcome to commitizen!

Answer the following questions to configure your project.
For further configuration, visit:

https://commitizen-tools.github.io/commitizen/config/

? Please choose a supported config file:  pyproject.toml
? Please choose a cz (commit rule): (default: cz_conventional_commits) cz_conventional_commits
? Choose the source of the version: uv: Get and set version from pyproject.toml and uv.lock
No Existing Tag. Set tag to v0.0.1
? Choose version scheme:  semver2
? Please enter the correct version format: (default: "$version")
? Create changelog automatically on bump Yes
? Keep major version zero (0.x) during breaking changes Yes
? What types of pre-commit hook you want to install? (Leave blank if you don't want to install) done (2 selections)
commitizen already in pre-commit config
commitizen pre-commit hook is now installed in your '.git'


You can bump the version running:

	cz bump

Configuration complete 🚀

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

設定ファイルの選択

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

ルールの選択

cz_conventional_commitsは、Conventional Commitsのルールに従ったコミットメッセージを生成します。

プロバイダーの選択

バージョン番号を参照する先を選択します。 選択肢の詳細は、前述の「プロバイダーしたい（version_provider）」を参照してください。 uvでプロジェクトを管理している場合はuvを、 それ以外のPythonプロジェクトではpep621を選ぶのがオススメです。

スキーマの選択

バージョン番号の表記形式を選択します。 選択肢の詳細は、前述の「スキーマしたい（version_scheme）」を参照してください。 迷ったらデフォルトのsemver2のままでよいです。

CHANGELOG自動生成の選択

cz bump実行時に--changelogオプションを付けなくても、 自動的にCHANGELOG.mdが更新されるようにするか選択します。 Yesを選ぶと、update_changelog_on_bump = trueが設定されます。

バージョン0の選択

破壊的変更（feat!:など）をコミットしたときに、 メジャーバージョンを0のまま維持するか選択します。 Yesを選ぶと、major_version_zero = trueが設定され、 メジャーバージョンが上がらずマイナーバージョンとして扱われます。 まだ安定版としてリリースしていないプロジェクトではYesを選ぶとよいです。

フックの選択

pre-commitフックを一緒にインストールするか選べます。

コミットしたい（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 --incremental

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

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

推奨される使い方

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

バージョンアップしたい（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とcommit-msgフックをスキップ

注釈

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

フックしたい（commitizen）

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

repos:
- repo: https://github.com/commitizen-tools/commitizen
  rev: v4.17.1
  hooks:
  - id: commitizen
  - id: commitizen-branch
    stages:
    - pre-push

id: commitizenは、デフォルトでcommit-msgステージで実行され、 コミットメッセージが保存されたあとに検証します。 これにより、セマンティック・バージョニングに従わないコミットメッセージは自動的に拒否されます。

id: commitizen-branchは、デフォルトでpre-pushステージで実行され、 現在のブランチにある（デフォルトブランチにはまだない）すべてのコミットメッセージをまとめて検証します。 コミット時ではなく、プッシュ時やCIなど、あとからまとめてチェックしたい場合に使います。 cz init実行時の「What types of pre-commit hook you want to install?」の質問で、 両方選択すると上記の設定が生成されます。