mcpField
C
Commitizen

Commitizen

公式
github.com開発ツール17.5kcz8 週間前に更新
リポジトリ公式サイト

Commitizen について

Commitizen は開発者を対話的なコマンドラインインターフェースで誘導し、Conventional Commits 規約に従ったコミットメッセージを作成させます。チーム全体で一貫したメッセージ形式を保証し、自動化ツールがコミットデータを簡単に解析できるようにします。

主な機能

  1. 01コミットタイプ、スコープ、説明、破壊的変更をプロンプトで入力する
  2. 02Conventional Commits アダプタでプロジェクト設定を初期化する
  3. 03チーム全体でコミットメッセージ構造を統一する
  4. 04git commit の代わりに git cz でガイド付きコミットを作成する

活用シーン

  1. 01開発チーム全体でコミットメッセージ形式を統一する
  2. 02変更ログの自動生成とバージョニング用に構造化データを提供する
  3. 03コードレビューとコミット履歴の形式の不一貫性を減らす

インストール

OS またはパッケージマネージャーを選び、コマンドをターミナルで実行します。

$
npm install -g commitizen

インストール後にcz --versionを実行して確認します。

コマンド例

よく使うコマンドを使う順に並べています。

01
cz init cz-conventional-changelog --save-dev
02
git cz

詳細

コントリビューター向けのCommitizen

Commitizenを使ってコミットすると、コミット時に必須のコミットフィールドを入力するよう求められます。後でGitコミットフックが実行されてコミットを拒否するまで待つ必要はありません（ただし、こちらも引き続き役立つ場合があります）。推奨される形式を探すためにCONTRIBUTING.mdを調べる必要もありません。コミットメッセージの書式についてすぐにフィードバックを受け取り、必須フィールドの入力を求められます。

Open Collectiveの支援者 Open Collectiveのスポンサー travis.ci Azureのビルドステータス codecov.io npmの月間ダウンロード数 現在のバージョン semantic-release stackoverflowのCommitizen

コマンドラインツールのインストール

Commitizenは現在、Node.js 12、14、16でテストされていますが、それより古いバージョンのNode.jsでも動作する可能性があります。また、npm 6以降が必要です。

次のコマンドを実行するだけでインストールできます（EACCESエラーが表示された場合は、npmの権限の修正が役立つ場合があります）。

npm install -g commitizen

コマンドラインツールの使用

リポジトリがCommitizenに対応している場合：

コミット時にgit commitの代わりにgit cz、または単にczを使ってください。czのエイリアスであるgit-czも使用できます。

または、npm 5.2以降を使用している場合は、グローバルにインストールする代わりにnpxを使用できます。

npx cz

または、npmスクリプトとして使用できます。

  ...
  "scripts": {
    "commit": "cz"
  }

Commitizenに対応したリポジトリで作業している場合は、必須フィールドの入力を求められ、プロジェクトのメンテナーが定めた規約に従ってコミットメッセージが整形されます。

Commitizenで追加してコミット

リポジトリがCommitizenに対応していない場合：

Commitizenに対応していないリポジトリで作業している場合、git czはgit commitと同じように動作しますが、npx czはstreamich/git-czアダプターを使用します。これを解決するには、まずリポジトリをCommitizenに対応させてください

リポジトリを Commitizen 対応にする

この例では、AngularJS のコミットメッセージ規約、別名 conventional-changelog を使えるように、リポジトリを設定します。

まず、Commitizen の CLI ツールをインストールします。

npm install commitizen -g

次に、次のコマンドを入力して、cz-conventional-changelog アダプターを使うようにプロジェクトを初期化します。

# npm
commitizen init cz-conventional-changelog --save-dev --save-exact

# yarn
commitizen init cz-conventional-changelog --yarn --dev --exact

# pnpm
commitizen init cz-conventional-changelog --pnpm --save-dev --save-exact

古いアダプターを上書きして強制的にインストールする場合は、--force 引数を指定できます。詳しくは、commitizen help を実行してください。

上記のコマンドは、次の3つを実行します。

  1. cz-conventional-changelog アダプターの npm モジュールをインストールします
  2. package.json の dependencies または devDependencies に保存します
  3. 以下に示すように、package.json ファイルのルートに config.commitizen キーを追加します
...
  "config": {
    "commitizen": {
      "path": "cz-conventional-changelog"
    }
  }

また、Commitizen の設定は .czrc ファイルに追加することもできます。

{
  "path": "cz-conventional-changelog"
}

これは、コントリビューターがこのリポジトリにコミットする際に使用するアダプターを Commitizen に伝えるだけです。

commitizen.path は require.resolve で解決され、次のものに対応しています。

  • npm モジュール
  • index.js ファイルを含む、process.cwd() からの相対ディレクトリ
  • .js 拡張子を持つ、process.cwd() からの相対ファイルのベース名
  • 相対ファイル名全体
  • 絶対パス

以前のバージョンの Commitizen では czConfig を使用していました。czConfig は非推奨になりました。Commitizen 3.0.0 より前に新しい形式へ移行してください。

オプション：Commitizen をローカルにインストールして実行する

Commitizen をローカルにインストールして実行すると、開発者がすべてのマシンでまったく同じバージョンの Commitizen を使用していることを確認できます。

npm install --save-dev commitizen で Commitizen をインストールします。

npm 5.2 以降では、 npx を使用して conventional changelog アダプターを初期化できます。

npx commitizen init cz-conventional-changelog --save-dev --save-exact

**以前のバージョンの npm（< 5.2）**では、コマンドを実際に使用するために ./node_modules/.bin/commitizen または ./node_modules/.bin/cz を実行できます。

次に、./node_modules/.bin/commitizen init cz-conventional-changelog --save-dev --save-exact を使用して、conventional changelog アダプターを初期化できます。

さらに、package.json ファイルに npm スクリプトを追加して、Commitizen のローカルバージョンを指定できます。

  ...
  "scripts": {
    "commit": "cz"
  }

これにより、ユーザーはコミットしたいときに npm run commit を実行するだけで、コミットを開始するために必要なプロンプトが表示されるため、より便利になります。

NOTE: husky などを使って precommit フックを使用している場合は、スクリプトに "commit" 以外の名前を付ける必要があります （例："cm": "cz"）。これは、npm スクリプトには、別のスクリプト名が xxx のときに、名前が prexxx のスクリプトを自動的に実行する「機能」があるためです。つまり、 スクリプト名を "commit" にすると、npm と husky が "precommit" スクリプトを2回実行します。回避するには、npm が起動する precommit スクリプトを防ぐ必要があります。

オプション：git commit で Commitizen を実行する

この例では、git フックと --hook コマンドラインオプションを使って、既存の git commit ワークフローに Commitizen を組み込む方法を示します。これは、Commitizen に詳しくない人からのコントリビューションにも適切なコミット形式を徹底したいプロジェクトメンテナーに役立ちます。

いずれかの方法を実装すると、git commit を実行したユーザーに、役立つコミットメッセージの作成を支援する対話型の Commitizen セッションが表示されます。

NOTE: この例では、プロジェクトがCommitizen をローカルにインストールして使用するように設定済みであることを前提としています。

従来の git フック

以下のコードで .git/hooks/prepare-commit-msg を更新します。

#!/bin/bash
exec < /dev/tty && node_modules/.bin/cz --hook || true
Husky

husky を使用している場合は、次の設定をプロジェクトの package.json ファイルに追加します。

"husky": {
  "hooks": {
    "prepare-commit-msg": "exec < /dev/tty && npx cz --hook || true"
  }
}

なぜ exec < /dev/tty を使うのですか？ デフォルトでは、git フックは対話型ではありません。このコマンドを使うと、ユーザーはフックの実行中にターミナルを使って Commitizen と対話できます。

おめでとうございます！リポジトリで Commitizen を使えるようになりました。さっそくアピールしましょう！

次の Markdown を使って、README に「Commitizen friendly」バッジを追加します。

[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)

バッジは次のように表示されます。

Commitizen friendly

新しいコントリビューターが Commitizen のインストール方法や使い方を学べるように、README.md または CONTRIBUTING.md ファイルに Commitizen プロジェクトについて記載するか、リンクを追加するとよいでしょう。

グローバルユーティリティとしての Conventional commit メッセージ

まだインストールしていない場合は、commitizen をグローバルにインストールします。

npm install -g commitizen

お好みの commitizen アダプター（例：cz-conventional-changelog）をグローバルにインストールします。

npm install -g cz-conventional-changelog

home ディレクトリに .czrc ファイルを作成し、path にグローバルにインストールしたお好みの commitizen アダプターを指定します。

echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc

準備は完了です！任意の git リポジトリに cd して、git commit の代わりに git cz を使うと、commitizen のプロンプトが表示されます。

ヒント：git cz では、git commit のすべての options を使えます。たとえば、git cz -a のように指定できます。

リポジトリが Node.js プロジェクトの場合、Commitizen を使えるようにするのはとても簡単です。

リポジトリで既に Commitizen を使える場合は、グローバルにインストールされたアダプターではなく、ローカルの commitizen アダプターが使用されます。

マルチリポジトリプロジェクト向け Commitizen

多くのプロジェクトを保守している場合、すべてのプロジェクトで単一のコミットメッセージ形式を標準化したいことがあるでしょう。Commitizen のフロントエンドとして動作する独自の node モジュールを作成できます。

1. 独自のエントリーポイントスクリプトを作成する
// my-cli.js

#!/usr/bin/env node
"use strict";

const path = require('path');
const bootstrap = require('commitizen/dist/cli/git-cz').bootstrap;

bootstrap({
  cliPath: path.join(__dirname, '../../node_modules/commitizen'),
  // this is new
  config: {
    "path": "cz-conventional-changelog"
  }
});
2. スクリプトを package.json ファイルに追加する
// package.json

{
  "name": "company-commit",
  "bin": "./my-cli.js",
  "dependencies": {
    "commitizen": "^2.7.6",
    "cz-conventional-changelog": "^1.1.5"
  }
}
3. npm に公開して使用する！
npm install --save-dev company-commit

./node_modules/.bin/company-commit

アダプター

プロジェクトやビルドプロセスごとに要件が異なるため、Commitizen を拡張しやすいようにしています。あらかじめ用意されたアダプターから選ぶことも、独自のアダプターを作成することもできます。利用できる優れたアダプターをいくつかご紹介します。

アダプターを作成するには、これらの優れたアダプターのいずれかをフォークし、ニーズに合わせて変更してください。Inquirer.js のインスタンスを渡しますが、必要に応じて任意の方法で入力を取得できます。文字列を指定して commit コールバックを呼び出すだけで大丈夫です。npm に公開すれば、準備完了です！

失敗したコミットの再試行

バージョン 2.7.1 以降では、git cz --retry コマンドを使って最後のコミットを再試行できます。これは、git の precommit フックでテストを実行するよう設定している場合に便利です。この場合、Commitizen でコミットを試み、Commitizen のすべての項目を苦労して入力したものの、テストが失敗することがあります。以前の Commitizen のバージョンでは、テストを修正した後、すべての項目を再度入力する必要がありました。そこで再試行コマンドの出番です。Commitizen は、項目を再入力しなくても、このリポジトリで最後に試みたコミットを再試行します。

Commitizen のバージョンやアダプターをアップグレードした場合、またはホームディレクトリや一時ディレクトリにある commitizen.json ファイルを削除した場合、再試行キャッシュが消去されることがあります。また、コミットキャッシュはリポジトリのファイルシステム上のパスを使用するため、リポジトリを移動したりパスを変更したりすると、コミットを再試行できません。これは特殊なケースですが、リポジトリを含むフォルダーを移動する状況では混乱を招く可能性があります。

npm スクリプトから cz を実行している場合（たとえば、スクリプト名が commit の場合）、次のいずれかを行う必要があります。

  • スクリプトの引数として -- --retry を渡します。例：npm run commit -- --retry
  • npx を使って cz 実行ファイルを直接見つけて呼び出します。例：npx cz --retry

最後の 2 つの方法では、引数の前に -- を渡す必要はありませんが、最初の方法では必要です。

プロジェクトメンテナー向けのCommitizen

プロジェクトメンテナーは、リポジトリをCommitizenに対応させることで、既存のコミットメッセージ規約を選択したり、独自のコミットメッセージ規約を作成したりできます。リポジトリのコントリビューターがCommitizenを使用すると、コミット時に適切な項目の入力を求められます。

さらに活用する

Commitizenは単体でも優れていますが、ほかの素晴らしいオープンソースツールと組み合わせると、さらに力を発揮します。Kent C. Doddsが、Egghead.ioのシリーズオープンソースJavaScriptライブラリの書き方で、その方法を紹介しています。多くの考え方は、JavaScript以外のプロジェクトにも応用できます。

基本理念

Commitizenについて

Commitizenは、コントリビューターがオープンソースコミュニティの一員として適切に活動できるよう支援するオープンソースプロジェクトです。コミット時にコミットメッセージ規約に従うよう促すことで、それを実現します。また、プロジェクトメンテナーがリポジトリで事前に定義されたコミットメッセージ規約を作成または使用できるようにし、今後のコントリビューターに期待する内容をより適切に伝えられるようにします。

Commitizenとコミットフック

両方です！CommitizenはGitのコミットフックに取って代わるものではありません。むしろ、コミットフックと併用して、コントリビューターに一貫した快適な体験を提供することを目的としています。Commitizenはコミットコマンドを宣言的なアクションとして扱います。コントリビューターは、プロジェクトに貢献する意思を宣言しています。従うべきルールを定めるのは、メンテナーであるあなたです。

プロジェクトで使用するアダプターを定義することで、これを実現できます。アダプターを使用すると、複数のプロジェクトで同じコミットメッセージ規約を共有できます。アダプターの良い例として、cz-conventional-changelogアダプターがあります。

関連プロジェクト

作者とコントリビューター

@JimTheDev（Jim Cummins、作者） @kentcdodds @accraze @kytwb @Den-dp

Commitizenを実現するg​​ulp-gitプロジェクトを手がけた@stevelacyに、特別な感謝を申し上げます。

コントリビューター

このプロジェクトは、貢献してくださったすべての方のおかげで成り立っています。[貢献する]。 README の画像

支援者

すべての支援者の皆さま、ありがとうございます！🙏 [支援者になる]

README の画像

スポンサー

スポンサーになって、このプロジェクトを支援してください。ロゴがここに表示され、ウェブサイトへのリンクが設定されます。[スポンサーになる]

README の画像 README の画像 README の画像 README の画像 README の画像 README の画像 README の画像 README の画像 README の画像 README の画像

コメント

Markdown 対応