Initial commit

2025-11-29 18:49:58 +08:00
commit 5007abf04b
89 changed files with 44129 additions and 0 deletions
--- a/skills/clang-format/references/index.md
+++ b/skills/clang-format/references/index.md
@@ -0,0 +1,238 @@
+# 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