Jamie-BitFlight/clang-format

clang-format Configuration

Configure the clang-format code formatting tool using ready-to-use templates, integration scripts, and comprehensive reference documentation.

Purpose

This skill provides procedural workflows for clang-format configuration tasks:

• Create new .clang-format files from proven templates
• Analyze existing code style and generate matching configurations
• Set up editor and git integration with bundled scripts
• Troubleshoot formatting behavior using reference documentation

Workflow Routing by Trigger Type

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.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

Bundled Resources

Configuration Templates (assets/configs/)

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 limit
• linux-kernel.clang-format - Linux kernel coding standards (tabs, K&R braces)
• microsoft-visual-studio.clang-format - Microsoft/Visual Studio conventions
• modern-cpp17-20.clang-format - Modern C++17/20 style with contemporary idioms
• compact-dense.clang-format - Compact style for space-constrained environments
• readable-spacious.clang-format - Spacious style prioritizing readability
• multi-language.clang-format - Multi-language configuration (C++, JavaScript, Java)

When to use templates: Start new projects, establish team standards, or quickly test formatting approaches.

Integration Scripts (assets/integrations/)

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-save
• emacs-clang-format.el - Emacs configuration for clang-format integration

When 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.

Reference Documentation (references/)

Detailed documentation organized by category:

Quick Navigation:

• index.md - Overview and documentation hub
• quick-reference.md - Complete working configurations with explanations
• cli-usage.md - Command-line usage, editor setup, CI/CD integration

Option Categories (01-09.md):

1. 01-alignment.md - Vertical alignment of declarations, assignments, operators
2. 02-breaking.md - Line breaking and wrapping rules
3. 03-braces.md - Brace placement styles (K&R, Allman, GNU, etc.)
4. 04-indentation.md - Indentation rules and special cases
5. 05-spacing.md - Whitespace control around operators, keywords
6. 06-includes.md - Include/import organization and sorting
7. 07-languages.md - Language-specific options for C++, Java, JavaScript
8. 08-comments.md - Comment formatting and reflow
9. 09-advanced.md - Penalty system, raw string formatting, experimental features

Complete Reference (complete/):

• clang-format-cli.md - Full command-line interface documentation
• clang-format-style-options.md - All 194 style options with examples

Common Workflows

Creating New Configuration from Template

To create a new .clang-format file:

1. Identify requirements (style guide, team preferences, language)
2. Select closest template from assets/configs/
3. Copy template to project root as .clang-format
4. Test formatting: clang-format --dry-run file.cpp
5. Customize specific options using references/01-09.md as needed
6. Verify changes: clang-format file.cpp | diff - file.cpp

Example:

# 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

Analyzing Existing Code Style

To generate configuration matching existing code:

1. Examine code samples for formatting patterns
2. Identify key characteristics:
   • Brace placement → consult references/03-braces.md
   • Indentation (spaces/tabs, width) → consult references/04-indentation.md
   • Spacing (operators, keywords) → consult references/05-spacing.md
   • Line breaking (column limit, wrapping) → consult references/02-breaking.md
   • Alignment patterns → consult references/01-alignment.md
3. Map patterns to closest base style in references/quick-reference.md
4. Start with that template from assets/configs/
5. Override specific options to match observed patterns
6. Test on representative code samples
7. Iterate until formatting matches existing style

This workflow minimizes whitespace-only changes when introducing clang-format to existing projects.

Setting Up Editor Integration

To enable format-on-save in editors:

Vim:

1. Copy assets/integrations/vimrc-clang-format.vim content to .vimrc
2. Restart Vim or source configuration
3. Save any C/C++/Java file to trigger formatting

Emacs:

1. Copy assets/integrations/emacs-clang-format.el to Emacs config
2. Restart Emacs or evaluate configuration
3. Save any supported file to trigger formatting

Other editors: Consult references/cli-usage.md for VS Code, CLion, and other editor setup instructions.

Setting Up Git Hook for Formatting

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:

1. Copy assets/integrations/pre-commit to .git/hooks/pre-commit
2. Make executable: chmod +x .git/hooks/pre-commit
3. Test by staging and committing changes

The hook formats only staged files, preserving unstaged changes.

Troubleshooting Formatting Issues

When formatting produces unexpected results:

1. Verify configuration detection: clang-format --dump-config file.cpp
2. Check command options in references/cli-usage.md
3. Identify affected formatting category (braces, spacing, breaking, etc.)
4. Consult relevant category guide in references/01-09.md
5. Test isolated options: create minimal config with suspect option
6. For comprehensive option details, check references/complete/clang-format-style-options.md

Setting Up CI/CD Formatting Checks

To enforce formatting in continuous integration:

1. Review CI examples in references/cli-usage.md
2. Add clang-format check to pipeline:

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

3. Configure to fail build on formatting violations
4. Document formatting requirements for contributors

Key Concepts

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.

Testing Configurations

# 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}

Navigation Strategy

For most tasks, follow this progression:

1. Start with templates: Browse assets/configs/ for ready-to-use configurations
2. Quick reference: Check references/quick-reference.md for complete configurations with explanations
3. Category guides: Consult references/01-09.md for specific option categories
4. CLI usage: Reference references/cli-usage.md for command-line and integration details
5. Complete reference: Use references/complete/ for exhaustive option documentation

When analyzing code or troubleshooting, identify the formatting aspect (braces, spacing, alignment, etc.) and jump directly to the relevant category guide in references/.