clang-format

clang-format 設定

すぐに使えるテンプレート、統合スクリプト、包括的なリファレンスドキュメントを使って、clang-format コードフォーマットツールを設定します。

目的

このスキルでは、clang-format の設定タスクに対応するため、手順に沿ったワークフローを提供します。

• 実績のあるテンプレートから新しい .clang-format ファイルを作成する
• 既存のコードスタイルを分析し、それに合った設定を生成する
• 同梱スクリプトを使ってエディターや git との連携を設定する
• リファレンスドキュメントを使ってフォーマットの動作に関する問題を解決する

トリガーの種類に応じたワークフローの振り分け

呼び出されたら、どのトリガーが発生したかに応じて適切なワークフローに振り分けます。

トリガー 1：clang-format への明示的な言及 → ユーザーが特定のオプションについて尋ねている場合：該当するカテゴリの references/01-09.md を参照 → ユーザーが完全なリファレンスを求めている場合：references/complete/clang-format-style-options.md を案内 → ユーザーが CLI の使い方について尋ねている場合：references/cli-usage.md を参照

トリガー 2：コードスタイルの分析依頼 → 以下の「既存のコードスタイルを分析する」ワークフローに従う → コードサンプルを体系的に調べる（波括弧→インデント→空白→改行→配置）→ assets/configs/ の中から最も近いテンプレートにパターンを対応付ける → 一時的な設定ファイル「/tmp/<reponame>/hypothesis.clang-format」として初期設定の仮説を生成する → 影響を検証する：代表的なサンプルを 3～5 個選び、clang-format --style="/tmp/<repo_name>/hypothesis_<number>.clang-format" file.cpp | diff - file.cpp を実行する → 重み付けスコアリングを使って影響を測定する：• 指標 1：行数の変化（追加／削除された行数）- 重み 10 • 指標 2：行内の空白の変化（既存の行内のスペース）- 重み 1 • 影響スコア =（行数の変化 × 10）+（空白の変化 × 1）• スコアが低いほど、リベース時の競合、将来の git-diff 分析、マージリクエストの変更レビューへの影響が小さくなり、設定として優れています → 反復する：影響の大きい設定オプションを調整し、再テストしてスコアを比較する → 一貫したスタイルの適用を維持しながら、達成可能な最小スコアに達するまで繰り返す → ユーザーに報告する：最終的な影響スコアと内訳（行の変更と空白の変更）、テストしたすべての仮説とスコアを示す比較表、変更内容を示す差分の例（ユーザーが任意のファイルに対して自分でテストできるコマンド付き）、選択した設定の根拠を提示する → 設定を確定する前に、ユーザーの承認を待つ → 承認後にのみ、最終的な設定ファイルを提示する

トリガー 3：設定ファイルの操作 → 新規作成の場合：「テンプレートから新しい設定を作成する」ワークフローに従う → 既存の設定を変更する場合：現在の設定を読み、必要な変更を特定し、該当するカテゴリガイドを参照する → コードから生成する場合：トリガー 2 のワークフローを使用する（コードスタイルの分析）

トリガー 4：フォーマット動作の調査 → 以下の「フォーマットの問題を解決する」ワークフローに従う → --dump-config を使って設定の検出を確認する → 該当するカテゴリを特定し、references/0X.md ガイドを参照する → 最小限の設定でオプションを個別にテストする

トリガー 5：スタイルオプションに関する問い合わせ → 質問をカテゴリに対応付ける：波括弧→03、インデント→04、空白→05、配置→01、改行→02 → references/ 内の該当するカテゴリガイドを参照する → 該当する場合は quick-reference.md の例を提示する

トリガー 6：変更を最小限に抑える依頼 → 現在のパターンに合わせるため、「既存のコードスタイルを分析する」ワークフローを使う → 変更を最小限にするため、最も近いテンプレートを起点にすることを重視する → プロジェクト全体に適用する前に、代表的なサンプルでテストする → 維持したパターンと標準化したパターンを記録する

同梱リソース

設定テンプレート（assets/configs/）

一般的なシナリオ向けに最適化された、すぐに使える 7 つの .clang-format テンプレートです。

• google-cpp-modified.clang-format - 4 スペースのインデント、120 列の上限を採用した Google C++ スタイル
• linux-kernel.clang-format - Linux カーネルのコーディング規約（タブ、K&R の波括弧）
• microsoft-visual-studio.clang-format - Microsoft／Visual Studio の規約
• modern-cpp17-20.clang-format - 現代的なイディオムを取り入れたモダンな C++17／20 スタイル
• compact-dense.clang-format - スペースが限られた環境向けのコンパクトなスタイル
• readable-spacious.clang-format - 読みやすさを優先したゆとりのあるスタイル
• multi-language.clang-format - 複数言語（C++、JavaScript、Java）向けの設定

テンプレートの使用場面：新しいプロジェクトの開始、チーム標準の策定、書式設定方法のすばやいテストに使用します。

統合スクリプト（assets/integrations/）

エディターおよび Git との統合スクリプトが 3 つあります。

• pre-commit - ステージされたファイルを自動で書式設定する Git フックスクリプト（pre-commit または prek フレームワークで動作）
• vimrc-clang-format.vim - 保存時に書式設定するための Vim 設定
• emacs-clang-format.el - clang-format と統合するための Emacs 設定

統合機能の使用場面：開発ワークフローに自動書式設定を導入する場合に使用します。

注：pre-commit フックスクリプトは、pre-commit フレームワーク（Python）と prek（Rust 製の代替ツール）の両方で動作します。どちらのフレームワークも、同一の構文を使用する .pre-commit-config.yaml を使用します。

リファレンスドキュメント（references/）

カテゴリー別にまとめられた詳細なドキュメントです。

クイックナビゲーション：

• index.md - 概要とドキュメントのハブ
• quick-reference.md - 説明付きの、すぐに使える完全な設定
• cli-usage.md - コマンドラインの使い方、エディターの設定、CI/CD との統合

オプションのカテゴリー（01-09.md）：

1. 01-alignment.md - 宣言、代入、演算子の垂直方向の揃え方
2. 02-breaking.md - 改行と折り返しの規則
3. 03-braces.md - 波括弧の配置スタイル（K&R、Allman、GNU など）
4. 04-indentation.md - インデントの規則と特殊なケース
5. 05-spacing.md - 演算子やキーワードの前後の空白の制御
6. 06-includes.md - include／import の整理と並べ替え
7. 07-languages.md - C++、Java、JavaScript 向けの言語固有のオプション
8. 08-comments.md - コメントの書式設定と再整形
9. 09-advanced.md - ペナルティシステム、生文字列の書式設定、実験的機能

完全なリファレンス（complete/）：

• clang-format-cli.md - コマンドラインインターフェースの全ドキュメント
• clang-format-style-options.md - すべての 194 個のスタイルオプションと例

一般的なワークフロー

テンプレートから新しい設定を作成する

新しい .clang-format ファイルを作成するには：

1. 要件（スタイルガイド、チームの好み、言語）を確認します
2. assets/configs/ から最も近いテンプレートを選びます
3. テンプレートをプロジェクトのルートに .clang-format としてコピーします
4. 書式設定をテストします：clang-format --dry-run file.cpp
5. 必要に応じて、references/01-09.md を参照しながら特定のオプションをカスタマイズします
6. 変更を確認します：clang-format file.cpp | diff - file.cpp

例：

# Copy Google C++ template
cp assets/configs/google-cpp-modified.clang-format /path/to/project/.clang-format

# Test on sample file
clang-format --dry-run /path/to/project/src/main.cpp

# Apply if satisfied
clang-format -i /path/to/project/src/*.cpp

既存のコードスタイルを分析する

既存のコードに合わせた設定を生成するには：

1. コードサンプルを調べて、書式設定のパターンを確認します
2. 主な特徴を特定します：
   • 波括弧の配置 → references/03-braces.md を参照
   • インデント（スペース／タブ、幅）→ references/04-indentation.md を参照
   • 空白（演算子、キーワード）→ references/05-spacing.md を参照
   • 改行（列の上限、折り返し）→ references/02-breaking.md を参照
   • 配置パターン → references/01-alignment.md を参照
3. references/quick-reference.md で、パターンに最も近い基本スタイルを見つけます
4. assets/configs/ からそのテンプレートを選びます
5. 観察したパターンに合うよう、特定のオプションを上書きします
6. 代表的なコードサンプルでテストします
7. 書式設定が既存のスタイルに合うまで調整を繰り返します

このワークフローにより、既存のプロジェクトに clang-format を導入する際の、空白のみの変更を最小限に抑えられます。

エディター連携の設定

エディターで保存時のフォーマットを有効にするには、次の手順に従います。

Vim：

1. assets/integrations/vimrc-clang-format.vim の内容を .vimrc にコピーします
2. Vim を再起動するか、設定を読み込みます
3. C/C++/Java ファイルを保存してフォーマットを実行します

Emacs：

1. assets/integrations/emacs-clang-format.el を Emacs の設定にコピーします
2. Emacs を再起動するか、設定を評価します
3. 対応するファイルを保存してフォーマットを実行します

その他のエディター：VS Code、CLion、その他のエディターの設定手順については、references/cli-usage.md を参照してください。

フォーマット用 Git フックの設定

オプション 1：pre-commit/prek フレームワークを使用する（推奨）：

.pre-commit-config.yaml で設定します。

repos:
  - repo: https://github.com/pre-commit/mirrors-clang-format
    rev: v19.1.7
    hooks:
      - id: clang-format

次に、pre-commit install または prek install を実行してインストールします。

オプション 2：手動で Git フックを設定する：

1. assets/integrations/pre-commit を .git/hooks/pre-commit にコピーします
2. 実行可能にします：chmod +x .git/hooks/pre-commit
3. 変更をステージングしてコミットし、動作を確認します

このフックはステージングされたファイルのみをフォーマットし、ステージングされていない変更は保持します。

フォーマットに関する問題のトラブルシューティング

フォーマット結果が予期しない場合は、次の手順に従います。

1. 設定が検出されていることを確認します：clang-format --dump-config file.cpp
2. references/cli-usage.md でコマンドオプションを確認します
3. 影響を受けているフォーマットの分類（波括弧、空白、改行など）を特定します
4. references/01-09.md で該当する分類のガイドを参照します
5. 該当するオプションだけを含む最小限の設定を作成し、単独でテストします
6. オプションの詳細については、references/complete/clang-format-style-options.md を確認します

CI/CD のフォーマットチェックを設定する

継続的インテグレーションでフォーマットを強制するには、次の手順に従います。

1. references/cli-usage.md の CI サンプルを確認します
2. パイプラインに clang-format のチェックを追加します。

   # Check formatting without modifying files
   clang-format --dry-run --Werror src/**/*.{cpp,h}
   

3. フォーマット違反がある場合にビルドが失敗するように設定します
4. コントリビューター向けにフォーマットの要件を文書化します

主な概念

ベーススタイル：事前定義された設定（LLVM、Google、Chromium、Mozilla、WebKit、Microsoft、GNU）は、出発点として使用できます。BasedOnStyle: Google を設定してから、特定のオプションを上書きします。

複数言語のサポート：Language: キーを使用して、1 つのファイル内で言語ごとに異なる設定を行えます。例については、assets/configs/multi-language.clang-format を参照してください。

ペナルティシステム：clang-format は、フォーマットの選択肢から選ぶ際にペナルティを使用します。ペナルティ値が高いほど、特定の選択肢が選ばれにくくなります。詳細は references/09-advanced.md を参照してください。

段階的な調整：要件に最も近いテンプレートから始め、少しずつカスタマイズします。代表的なコードサンプルを使って頻繁にテストしてください。

設定のテスト

# Preview changes without modifying file
clang-format --dry-run file.cpp

# Show diff of proposed changes
clang-format file.cpp | diff - file.cpp

# Apply formatting to file
clang-format -i file.cpp

# Format entire project
find src include -name '*.cpp' -o -name '*.h' | xargs clang-format -i

# Check formatting in CI (fail on violations)
clang-format --dry-run --Werror src/**/*.{cpp,h}

ナビゲーションの方法

ほとんどのタスクでは、次の順序で進めてください。

1. テンプレートから始める：すぐに使える設定を assets/configs/ で探します
2. クイックリファレンス：説明付きの完全な設定については、references/quick-reference.md を確認します
3. 分類別ガイド：特定のオプションの分類については、references/01-09.md を参照します
4. CLI の使用方法：コマンドラインと連携の詳細については、references/cli-usage.md を参照します
5. 完全リファレンス：オプションの網羅的なドキュメントには、references/complete/ を使用します

コードの分析やトラブルシューティングを行う際は、フォーマットの対象（波括弧、空白、配置など）を特定し、references/ 内の該当する分類別ガイドを直接参照してください。