239 lines
6.0 KiB
Markdown
239 lines
6.0 KiB
Markdown
# clang-format Configuration Skill
|
|
|
|
A comprehensive skill for configuring clang-format to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code.
|
|
|
|
## Navigation
|
|
|
|
### Quick Access
|
|
|
|
- [CLI Usage](cli-usage.md) - Command-line tools, flags, and integrations
|
|
- [Quick Reference](quick-reference.md) - Common patterns and complete examples
|
|
|
|
### Style Options by Category
|
|
|
|
1. [Alignment Options](01-alignment.md) - Align code elements consistently
|
|
2. [Breaking & Line Wrapping](02-breaking.md) - Control line breaks and wrapping
|
|
3. [Brace Styles](03-braces.md) - Configure brace placement and wrapping
|
|
4. [Indentation](04-indentation.md) - Control indentation behavior
|
|
5. [Spacing](05-spacing.md) - Fine-tune whitespace placement
|
|
6. [Include Organization](06-includes.md) - Sort and organize include directives
|
|
7. [Language-Specific](07-languages.md) - Options for specific languages
|
|
8. [Comments & Misc](08-comments.md) - Comment formatting and other options
|
|
9. [Advanced Options](09-advanced.md) - Experimental and advanced features
|
|
|
|
### Complete Reference Documentation
|
|
|
|
- [Full CLI Reference](complete/clang-format-cli.md) - Complete command-line documentation
|
|
- [Full Style Options](complete/clang-format-style-options.md) - Complete style configuration reference
|
|
|
|
## What is clang-format?
|
|
|
|
clang-format is a tool that automatically formats source code according to configurable style rules. It ensures consistent code formatting across your project and team.
|
|
|
|
**Supported Languages:**
|
|
|
|
- C/C++
|
|
- Java
|
|
- JavaScript/TypeScript
|
|
- JSON
|
|
- Objective-C
|
|
- Protocol Buffers
|
|
- C#
|
|
- Verilog
|
|
- TableGen
|
|
|
|
## Quick Start
|
|
|
|
### 1. Create a Configuration File
|
|
|
|
Generate a `.clang-format` file based on a predefined style:
|
|
|
|
```bash
|
|
clang-format -style=llvm -dump-config > .clang-format
|
|
```
|
|
|
|
**Available Base Styles:**
|
|
|
|
- `LLVM` - LLVM coding conventions
|
|
- `Google` - Google C++ Style Guide
|
|
- `GNU` - GNU coding style
|
|
- `Chromium` - Chromium project style
|
|
- `Microsoft` - Microsoft coding style
|
|
- `Mozilla` - Mozilla coding style
|
|
- `WebKit` - WebKit coding style
|
|
|
|
### 2. Customize Your Configuration
|
|
|
|
Edit `.clang-format` to customize specific options:
|
|
|
|
```yaml
|
|
# Start with a base style
|
|
BasedOnStyle: Google
|
|
|
|
# Customize specific options
|
|
IndentWidth: 4
|
|
ColumnLimit: 120
|
|
PointerAlignment: Left
|
|
```
|
|
|
|
### 3. Format Your Code
|
|
|
|
```bash
|
|
# Format a single file in-place
|
|
clang-format -i src/main.cpp
|
|
|
|
# Format multiple files
|
|
clang-format -i src/*.cpp include/*.h
|
|
|
|
# Check without modifying (dry run)
|
|
clang-format --dry-run src/main.cpp
|
|
|
|
# Format only changed lines in git
|
|
git clang-format
|
|
```
|
|
|
|
## Configuration File Structure
|
|
|
|
A `.clang-format` file uses YAML format with key-value pairs:
|
|
|
|
```yaml
|
|
---
|
|
# Language-specific settings
|
|
Language: Cpp
|
|
|
|
# Base style to inherit from
|
|
BasedOnStyle: LLVM
|
|
|
|
# Indentation
|
|
IndentWidth: 4
|
|
UseTab: Never
|
|
TabWidth: 4
|
|
|
|
# Line length
|
|
ColumnLimit: 100
|
|
|
|
# Braces
|
|
BreakBeforeBraces: Allman
|
|
|
|
# Spacing
|
|
SpaceBeforeParens: ControlStatements
|
|
|
|
# Pointer alignment
|
|
PointerAlignment: Left
|
|
|
|
# Include sorting
|
|
SortIncludes: true
|
|
```
|
|
|
|
## Common Workflows
|
|
|
|
### Format on Commit
|
|
|
|
Format only staged changes before committing:
|
|
|
|
```bash
|
|
git clang-format
|
|
```
|
|
|
|
### Format Entire Project
|
|
|
|
```bash
|
|
find src include -name '*.cpp' -o -name '*.h' | xargs clang-format -i
|
|
```
|
|
|
|
### Check Formatting in CI
|
|
|
|
```bash
|
|
clang-format --dry-run --Werror src/*.cpp include/*.h
|
|
```
|
|
|
|
### Ignore Specific Files
|
|
|
|
Create `.clang-format-ignore`:
|
|
|
|
```text
|
|
# Ignore third-party code
|
|
third_party/**
|
|
external/**
|
|
|
|
# Ignore generated files
|
|
*.pb.cc
|
|
*.pb.h
|
|
```
|
|
|
|
## Editor Integration
|
|
|
|
clang-format integrates with popular editors:
|
|
|
|
- **VS Code**: Install "Clang-Format" extension
|
|
- **CLion**: Built-in support (detects `.clang-format`)
|
|
- **Vim**: Use clang-format.py script
|
|
- **Emacs**: Use clang-format.el
|
|
|
|
See [CLI Usage](cli-usage.md) for detailed integration instructions.
|
|
|
|
## Finding Style Options
|
|
|
|
Options are organized by category:
|
|
|
|
- **Need to align assignments?** → [Alignment Options](01-alignment.md)
|
|
- **Control where lines break?** → [Breaking & Line Wrapping](02-breaking.md)
|
|
- **Configure brace placement?** → [Brace Styles](03-braces.md)
|
|
- **Adjust indentation?** → [Indentation](04-indentation.md)
|
|
- **Fine-tune spacing?** → [Spacing](05-spacing.md)
|
|
- **Organize includes?** → [Include Organization](06-includes.md)
|
|
- **Language-specific needs?** → [Language-Specific](07-languages.md)
|
|
|
|
## Example Configurations
|
|
|
|
See [Quick Reference](quick-reference.md) for complete configuration examples:
|
|
|
|
- Google C++ style customized
|
|
- Linux kernel style
|
|
- Corporate/Microsoft style
|
|
- Modern C++ style
|
|
|
|
## Documentation Structure
|
|
|
|
This skill is organized into:
|
|
|
|
1. **Navigable sections** - Categorized options for easy browsing
|
|
2. **Complete reference** - Full documentation for deep dives
|
|
3. **Quick reference** - Ready-to-use configuration examples
|
|
|
|
## Best Practices
|
|
|
|
1. **Version control** your `.clang-format` file in the repository root
|
|
2. **Start with a base style** that matches your existing conventions
|
|
3. **Make minimal changes** to the base style to reduce maintenance
|
|
4. **Document deviations** from standard styles in comments
|
|
5. **Test on representative code** before applying project-wide
|
|
6. **Use git integration** to format only changed lines
|
|
7. **Set up editor integration** for automatic formatting
|
|
8. **Create `.clang-format-ignore`** for files that shouldn't be formatted
|
|
|
|
## Troubleshooting
|
|
|
|
**Configuration not found?**
|
|
|
|
- clang-format searches for `.clang-format` or `_clang-format` from the source file's directory upward
|
|
- Use `-style=file:/path/to/.clang-format` to specify explicitly
|
|
|
|
**Unknown options warning?**
|
|
|
|
- Use `--Wno-error=unknown` to allow formatting with unknown (newer) options
|
|
- This happens when your config has options not supported by your clang-format version
|
|
|
|
**Want to check effective config?**
|
|
|
|
```bash
|
|
clang-format -dump-config file.cpp
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
- Browse [Style Options by Category](#style-options-by-category) to customize formatting
|
|
- Check [Quick Reference](quick-reference.md) for complete working examples
|
|
- Review [CLI Usage](cli-usage.md) for advanced command-line usage
|
|
- Consult full reference documentation for comprehensive details
|