Configure the clang-format code formatting tool using ready-to-use templates, integration scripts, and comprehensive reference documentation.
Configures clang-format with templates, integration scripts, and documentation for consistent code styling.
/plugin marketplace add jamie-bitflight/claude_skills/plugin install clang-format@jamie-bitflight-skillsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
assets/configs/compact-dense.clang-formatassets/configs/google-cpp-modified.clang-formatassets/configs/linux-kernel.clang-formatassets/configs/microsoft-visual-studio.clang-formatassets/configs/modern-cpp17-20.clang-formatassets/configs/multi-language.clang-formatassets/configs/readable-spacious.clang-formatassets/integrations/emacs-clang-format.elassets/integrations/pre-commitassets/integrations/vimrc-clang-format.vimreferences/01-alignment.mdreferences/02-breaking.mdreferences/03-braces.mdreferences/04-indentation.mdreferences/05-spacing.mdreferences/06-includes.mdreferences/07-languages.mdreferences/08-comments.mdreferences/09-advanced.mdreferences/cli-usage.mdConfigure the clang-format code formatting tool using ready-to-use templates, integration scripts, and comprehensive reference documentation.
This skill provides procedural workflows for clang-format configuration tasks:
Once invoked, route to appropriate workflow based on which trigger fired:
Trigger 1: Explicit clang-format mention → If user asks about specific options: Consult references/01-09.md for relevant category → If user needs complete reference: Direct to references/complete/clang-format-style-options.md → If user asks about CLI usage: Reference references/cli-usage.md
Trigger 2: Code style analysis request → Follow "Analyzing Existing Code Style" workflow below → Examine code samples systematically (braces→indentation→spacing→breaking→alignment) → Map patterns to closest template in assets/configs/ → Generate initial configuration hypothesis as a temporary configuration file "/tmp/<reponame>/hypothesis<number>.clang-format" → VERIFY IMPACT: Run clang-format --style="/tmp/<repo_name>/hypothesis_<number>.clang-format" file.cpp | diff - file.cpp on 3-5 representative samples → MEASURE IMPACT using weighted scoring: • Metric 1: Line count changes (lines added/removed) - weight 10 • Metric 2: In-line whitespace changes (spacing within existing lines) - weight 1 • Impact Score = (line_count_changes × 10) + (whitespace_changes × 1) • Lower score = lower impact to rebasing conflicts, future git-diff analysis, and merge request change reviews = better configuration → ITERATE: Adjust config options targeting highest-impact settings, re-test, compare scores → REPEAT until reaching minimal achievable score while maintaining consistent style enforcement → REPORT TO USER: Present winning configuration with: • Final impact score and breakdown (line changes vs whitespace changes) • Comparison table showing all tested hypotheses and their scores • Example diff snippets showing what will change, with commands for the user to test it themselves against files of their choice. • Rationale for selected configuration → AWAIT USER APPROVAL before finalizing configuration → Only after approval: provide final configuration file
Trigger 3: Configuration file operations → If creating new: Follow "Creating New Configuration from Template" workflow → If modifying existing: Read current config, identify changes needed, consult relevant category guide → If generating from code: Use Trigger 2 workflow (code style analysis)
Trigger 4: Formatting behavior investigation → Follow "Troubleshooting Formatting Issues" workflow below → Verify config detection with --dump-config → Identify affected category, consult relevant references/0X.md guide → Test isolated options with minimal config
Trigger 5: Style option inquiries → Map question to category: braces→03, indentation→04, spacing→05, alignment→01, breaking→02 → Reference specific category guide in references/ → Provide examples from quick-reference.md if applicable
Trigger 6: Minimal-disruption requests → Use "Analyzing Existing Code Style" workflow to match current patterns → Emphasize starting from closest template to minimize changes → Test on representative samples before project-wide application → Document which patterns were preserved vs normalized
Seven ready-to-use .clang-format templates optimized for common scenarios:
google-cpp-modified.clang-format - Google C++ style with 4-space indent, 120 column limitlinux-kernel.clang-format - Linux kernel coding standards (tabs, K&R braces)microsoft-visual-studio.clang-format - Microsoft/Visual Studio conventionsmodern-cpp17-20.clang-format - Modern C++17/20 style with contemporary idiomscompact-dense.clang-format - Compact style for space-constrained environmentsreadable-spacious.clang-format - Spacious style prioritizing readabilitymulti-language.clang-format - Multi-language configuration (C++, JavaScript, Java)When to use templates: Start new projects, establish team standards, or quickly test formatting approaches.
Three editor and git integration scripts:
pre-commit - Git hook script for automatic formatting of staged files (works with pre-commit or prek framework)vimrc-clang-format.vim - Vim configuration for format-on-saveemacs-clang-format.el - Emacs configuration for clang-format integrationWhen to use integrations: Set up automatic formatting in development workflow.
Note: The pre-commit hook script works with both the pre-commit framework (Python) and prek (Rust alternative). Both frameworks use .pre-commit-config.yaml with identical syntax.
Detailed documentation organized by category:
Quick Navigation:
index.md - Overview and documentation hubquick-reference.md - Complete working configurations with explanationscli-usage.md - Command-line usage, editor setup, CI/CD integrationOption Categories (01-09.md):
01-alignment.md - Vertical alignment of declarations, assignments, operators02-breaking.md - Line breaking and wrapping rules03-braces.md - Brace placement styles (K&R, Allman, GNU, etc.)04-indentation.md - Indentation rules and special cases05-spacing.md - Whitespace control around operators, keywords06-includes.md - Include/import organization and sorting07-languages.md - Language-specific options for C++, Java, JavaScript08-comments.md - Comment formatting and reflow09-advanced.md - Penalty system, raw string formatting, experimental featuresComplete Reference (complete/):
clang-format-cli.md - Full command-line interface documentationclang-format-style-options.md - All 194 style options with examplesTo create a new .clang-format file:
assets/configs/.clang-formatclang-format --dry-run file.cppclang-format file.cpp | diff - file.cppExample:
# 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
To generate configuration matching existing code:
references/03-braces.mdreferences/04-indentation.mdreferences/05-spacing.mdreferences/02-breaking.mdreferences/01-alignment.mdreferences/quick-reference.mdassets/configs/This workflow minimizes whitespace-only changes when introducing clang-format to existing projects.
To enable format-on-save in editors:
Vim:
assets/integrations/vimrc-clang-format.vim content to .vimrcEmacs:
assets/integrations/emacs-clang-format.el to Emacs configOther editors: Consult references/cli-usage.md for VS Code, CLion, and other editor setup instructions.
Option 1: Using pre-commit/prek framework (Recommended):
Configure in .pre-commit-config.yaml:
repos:
- repo: https://github.com/pre-commit/mirrors-clang-format
rev: v19.1.7
hooks:
- id: clang-format
Then install: pre-commit install or prek install
Option 2: Manual git hook:
assets/integrations/pre-commit to .git/hooks/pre-commitchmod +x .git/hooks/pre-commitThe hook formats only staged files, preserving unstaged changes.
When formatting produces unexpected results:
clang-format --dump-config file.cppreferences/cli-usage.mdreferences/complete/clang-format-style-options.mdTo enforce formatting in continuous integration:
references/cli-usage.md# Check formatting without modifying files
clang-format --dry-run --Werror src/**/*.{cpp,h}
Base Styles: Predefined configurations (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft, GNU) provide starting points. Set with BasedOnStyle: Google then override specific options.
Multi-Language Support: Configure different languages separately in single file using Language: key. See assets/configs/multi-language.clang-format for example.
Penalty System: clang-format uses penalties to choose between formatting alternatives. Higher penalty values discourage specific choices. See references/09-advanced.md for details.
Progressive Refinement: Start with template closest to requirements, then customize incrementally. Test frequently on representative code samples.
# 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}
For most tasks, follow this progression:
assets/configs/ for ready-to-use configurationsreferences/quick-reference.md for complete configurations with explanationsreferences/01-09.md for specific option categoriesreferences/cli-usage.md for command-line and integration detailsreferences/complete/ for exhaustive option documentationWhen analyzing code or troubleshooting, identify the formatting aspect (braces, spacing, alignment, etc.) and jump directly to the relevant category guide in references/.
This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.