clang-format Konfiguration

Was macht clang-format Konfiguration?

Konfiguriere das clang-format Code-Formatierungswerkzeug mit fertigen Vorlagen, Integrationsskripten und umfassender Referenzdokumentation.

Zweck

Diese Fähigkeit bietet prozedurale Workflows für clang-format Konfigurationsaufgaben:

• Erstelle neue .clang-format Dateien aus bewährten Vorlagen
• Analysiere vorhandenen Code-Stil und erstelle passende Konfigurationen
• Richte Editor- und Git-Integration mit mitgelieferten Skripten ein
• Behebe Formatierungsprobleme mithilfe der Referenzdokumentation

Workflow-Routing nach Auslöser-Typ

Nach der Aktivierung leite je nach auslösendem Ereignis an den entsprechenden Workflow weiter:

Auslöser 1: Explizite clang-format Erwähnung → Wenn der Benutzer nach bestimmten Optionen fragt: Konsultiere references/01-09.md für die relevante Kategorie → Wenn der Benutzer eine vollständige Referenz benötigt: Leite weiter zu references/complete/clang-format-style-options.md → Wenn der Benutzer nach CLI-Nutzung fragt: Verweise auf references/cli-usage.md

Auslöser 2: Code-Stil Analyseanfrage → Folge dem Arbeitsablauf „Analysieren eines bestehenden Code-Stils“ unten → Untersuche Codebeispiele systematisch (Klammern→Einrückung→Abstände→Zeilenumbrüche→Ausrichtung) → Ordne Muster der nächstgelegenen Vorlage in assets/configs/ zu → Erstelle eine erste Konfigurationshypothese als temporäre Konfigurationsdatei /tmp/<repo_name>/hypothesis_<number>.clang-format → ÜBERPRÜFE AUSWIRKUNGEN: Führe clang-format --style="/tmp/<repo_name>/hypothesis_<number>.clang-format" file.cpp | diff - file.cpp für 3–5 repräsentative Beispiele aus → MESSE AUSWIRKUNGEN mit gewichteter Bewertung: • Metrik 1: Änderungen der Zeilenanzahl (hinzugefügte/entfernte Zeilen) – Gewicht 10 • Metrik 2: Leerraumänderungen innerhalb von Zeilen (Abstände innerhalb bestehender Zeilen) – Gewicht 1 • Impact Score = (line_count_changes × 10) + (whitespace_changes × 1) • Niedrigerer Score = geringere Auswirkungen auf Rebase-Konflikte, zukünftige Git-Diff-Analysen und Merge-Request-Änderungsprüfungen = bessere Konfiguration → ITERIERE: Passe Konfigurationsoptionen mit dem höchsten Einfluss an, teste erneut, vergleiche Scores → WIEDERVEREINEN, bis die minimal erreichbare Punktzahl bei gleichzeitiger konsistenter Stildurchsetzung erreicht ist → BERICHTE AN BENUTZER: Präsentiere die gewinnende Konfiguration mit: • Endgültiger Impact Score und Aufschlüsselung (Zeilenänderungen vs. Leerraumänderungen) • Vergleichstabelle aller getesteten Hypothesen und deren Scores • Beispiel-Diff-Ausschnitte, die zeigen, was sich ändern wird, mit Befehlen, damit der Benutzer diese selbst an Dateien seiner Wahl testen kann. • Begründung für die ausgewählte Konfiguration → WARTE AUF BENUTZERZUSTIMMUNG, bevor die Konfiguration finalisiert wird → Nur nach Zustimmung: Bereitstellung der endgültigen Konfigurationsdatei

Auslöser 3: Konfigurationsdatei-Operationen → Bei Neuerstellung: Folge dem Arbeitsablauf „Neue Konfiguration aus Vorlage erstellen“ → Bei Änderung bestehender: Lese aktuelle Konfiguration, identifiziere erforderliche Änderungen, konsultiere relevante Kategorieanleitung → Bei Generierung aus Code: Verwende Auslöser 2 Workflow (Code-Stil Analyse)

Auslöser 4: Untersuchung von Formatierungsverhalten → Folge dem Arbeitsablauf „Fehlerbehebung bei Formatierungsproblemen“ unten → Überprüfe Konfigurationserkennung mit --dump-config → Identifiziere betroffene Kategorie, konsultiere relevante references/0X.md Anleitung → Teste isolierte Optionen mit minimaler Konfiguration

Auslöser 5: Anfragen zu Stiloptionen → Ordne Frage einer Kategorie zu: Klammern→03, Einrückung→04, Abstände→05, Ausrichtung→01, Zeilenumbrüche→02 → Konsultiere spezifische Kategorieanleitung in references/ → Gib Beispiele aus quick-reference.md, falls zutreffend

Auslöser 6: Anfragen mit minimaler Störung → Verwende Arbeitsablauf „Analysieren eines bestehenden Code-Stils“, um aktuelle Muster zu treffen → Betone, mit der nächstgelegenen Vorlage zu beginnen, um Änderungen zu minimieren → Teste an repräsentativen Beispielen vor der projektweiten Anwendung → Dokumentiere, welche Muster beibehalten und welche normalisiert wurden

Mitgelieferte Ressourcen

Konfigurationsvorlagen (assets/configs/)

Sieben einsatzbereite .clang-format Vorlagen, optimiert für häufige Szenarien:

• google-cpp-modified.clang-format – Google C++ Stil mit 4-Leerzeichen Einzug, 120 Spalten Grenze
• linux-kernel.clang-format – Linux Kernel Codierungsstandards (Tabs, K&R Klammern)
• microsoft-visual-studio.clang-format – Microsoft/Visual Studio Konventionen
• modern-cpp17-20.clang-format – Moderner C++17/20 Stil mit zeitgenössischen Redewendungen
• compact-dense.clang-format – Kompakter Stil für platzbeschränkte Umgebungen
• readable-spacious.clang-format – Großzügiger Stil mit Fokus auf Lesbarkeit
• multi-language.clang-format – Mehrsprachen-Konfiguration (C++, JavaScript, Java)

Wann Vorlagen verwenden: Starte neue Projekte, lege Teamstandards fest oder teste schnell Formatierungsansätze.

Integrationsskripte (assets/integrations/)

Drei Editor- und Git-Integrationsskripte:

• pre-commit – Git-Hook-Skript für automatische Formatierung gestagter Dateien (funktioniert mit pre-commit oder prek Framework)
• vimrc-clang-format.vim – Vim-Konfiguration für Formatieren-beim-Speichern
• emacs-clang-format.el – Emacs-Konfiguration für clang-format Integration

Wann Integrationen verwenden: Richte automatische Formatierung im Entwicklungsworkflow ein.

Hinweis: Das Pre-Commit-Hook-Skript funktioniert sowohl mit dem pre-commit Framework (Python) als auch mit prek (Rust-Alternative). Beide Frameworks verwenden .pre-commit-config.yaml mit identischer Syntax.

Referenzdokumentation (references/)

Detaillierte Dokumentation, organisiert nach Kategorien:

Schnellnavigation:

• index.md – Überblick und Dokumentations-Hub
• quick-reference.md – Vollständige funktionierende Konfigurationen mit Erklärungen
• cli-usage.md – Befehlszeilen-Nutzung, Editor-Setup, CI/CD-Integration

Optionskategorien (01-09.md):

1. 01-alignment.md – Vertikale Ausrichtung von Deklarationen, Zuweisungen, Operatoren
2. 02-breaking.md – Zeilenumbrüche und Umbruchregeln
3. 03-braces.md – Klammerplatzierungsstile (K&R, Allman, GNU, etc.)
4. 04-indentation.md – Einrückungsregeln und Sonderfälle
5. 05-spacing.md – Leerraumkontrolle um Operatoren, Schlüsselwörter
6. 06-includes.md – Include/Import-Organisation und Sortierung
7. 07-languages.md – Sprachspezifische Optionen für C++, Java, JavaScript
8. 08-comments.md – Kommentarformatierung und -umfluss
9. 09-advanced.md – Penalty-System, Raw-String-Formatierung, experimentelle Funktionen

Vollständige Referenz (complete/):

• clang-format-cli.md – Vollständige Befehlszeilen-Schnittstellendokumentation
• clang-format-style-options.md – Alle 194 Stiloptionen mit Beispielen

Allgemeine Workflows

Neue Konfiguration aus Vorlage erstellen

So erstellst du eine neue .clang-format Datei:

1. Ermittle Anforderungen (Style Guide, Teampräferenzen, Sprache)
2. Wähle die nächstgelegene Vorlage aus assets/configs/
3. Kopiere die Vorlage als .clang-format in das Projektwurzelverzeichnis
4. Teste die Formatierung: clang-format --dry-run file.cpp
5. Passe spezifische Optionen bei Bedarf mit references/01-09.md an
6. Überprüfe Änderungen: clang-format file.cpp | diff - file.cpp

Beispiel:

# Google C++ Vorlage kopieren
cp assets/configs/google-cpp-modified.clang-format /pfad/zum/projekt/.clang-format

# An Beispieldatei testen
clang-format --dry-run /pfad/zum/projekt/src/main.cpp

# Anwenden, wenn zufrieden
clang-format -i /pfad/zum/projekt/src/*.cpp

Analysieren eines bestehenden Code-Stils

So generierst du eine Konfiguration, die zu vorhandenem Code passt:

1. Untersuche Codebeispiele auf Formatierungsmuster
2. Identifiziere Schlüsselmerkmale:
   • Klammerplatzierung → konsultiere references/03-braces.md
   • Einrückung (Leerzeichen/Tabs, Breite) → konsultiere references/04-indentation.md
   • Abstände (Operatoren, Schlüsselwörter) → konsultiere references/05-spacing.md
   • Zeilenumbrüche (Spaltenlimit, Umbruch) → konsultiere references/02-breaking.md
   • Ausrichtungsmuster → konsultiere references/01-alignment.md
3. Ordne Muster dem nächstgelegenen Basisstil in references/quick-reference.md zu
4. Beginne mit dieser Vorlage aus assets/configs/
5. Überschreibe spezifische Optionen, um beobachtete Muster zu treffen
6. Teste an repräsentativen Codebeispielen
7. Wiederhole, bis die Formatierung zum bestehenden Stil passt

Dieser Workflow minimiert reine Leerraumänderungen bei der Einführung von clang-format in bestehenden Projekten.

Editor-Integration einrichten

So aktivierst du Formatieren-beim-Speichern in Editoren:

Vim:

1. Kopiere den Inhalt von assets/integrations/vimrc-clang-format.vim in die .vimrc
2. Starte Vim neu oder lade die Konfiguration
3. Speichere eine C/C++/Java-Datei, um die Formatierung auszulösen

Emacs:

1. Kopiere assets/integrations/emacs-clang-format.el in die Emacs-Konfiguration
2. Starte Emacs neu oder werte die Konfiguration aus
3. Speichere eine unterstützte Datei, um die Formatierung auszulösen

Andere Editoren: Konsultiere references/cli-usage.md für VS Code, CLion und andere Editor-Setup-Anleitungen.

Git-Hook für Formatierung einrichten

Option 1: Verwendung des pre-commit/prek Frameworks (Empfohlen):

Konfiguriere in .pre-commit-config.yaml:

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

Dann installieren: pre-commit install oder prek install

Option 2: Manueller Git-Hook:

1. Kopiere assets/integrations/pre-commit nach .git/hooks/pre-commit
2. Ausführbar machen: chmod +x .git/hooks/pre-commit
3. Teste durch Stagen und Committen von Änderungen

Der Hook formatiert nur gestagte Dateien und bewahrt ungestagte Änderungen.

Fehlerbehebung bei Formatierungsproblemen

Wenn die Formatierung unerwartete Ergebnisse liefert:

1. Überprüfe die Konfigurationserkennung: clang-format --dump-config datei.cpp
2. Überprüfe die Befehlsoptionen in references/cli-usage.md
3. Identifiziere die betroffene Formatierungskategorie (Klammern, Abstände, Zeilenumbrüche, etc.)
4. Konsultiere die relevante Kategorieanleitung in references/01-09.md
5. Teste isolierte Optionen: Erstelle eine minimale Konfiguration mit der verdächtigen Option
6. Für detaillierte Optionen siehe references/complete/clang-format-style-options.md

Einrichten von CI/CD-Formatierungsprüfungen

So erzwingst du Formatierung in der Continuous Integration:

1. Überprüfe CI-Beispiele in references/cli-usage.md
2. Füge clang-format Prüfung in die Pipeline ein:

   # Formatierung prüfen ohne Dateien zu ändern
   clang-format --dry-run --Werror src/**/*.{cpp,h}
   

3. Konfiguriere, dass der Build bei Formatierungsverstößen fehlschlägt
4. Dokumentiere Formatierungsanforderungen für Mitwirkende

Schlüsselkonzepte

Basisstile: Vordefinierte Konfigurationen (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft, GNU) bieten Ausgangspunkte. Setze mit BasedOnStyle: Google und überschreibe dann spezifische Optionen.

Mehrsprachenunterstützung: Konfiguriere verschiedene Sprachen separat in einer einzigen Datei mit dem Schlüssel Language:. Siehe assets/configs/multi-language.clang-format als Beispiel.

Penalty-System: clang-format verwendet Strafen, um zwischen Formatierungsalternativen zu wählen. Höhere Strafwerte verhindern bestimmte Entscheidungen. Siehe references/09-advanced.md für Details.

Progressive Verfeinerung: Beginne mit der Vorlage, die den Anforderungen am nächsten kommt, und passe dann schrittweise an. Teste häufig an repräsentativen Codebeispielen.

Testen von Konfigurationen

# Vorschau der Änderungen ohne Dateiänderung
clang-format --dry-run datei.cpp

# Zeige Diff der vorgeschlagenen Änderungen
clang-format datei.cpp | diff - datei.cpp

# Formatierung auf Datei anwenden
clang-format -i datei.cpp

# Ganzes Projekt formatieren
find src include -name '*.cpp' -o -name '*.h' | xargs clang-format -i

# Formatierung in CI prüfen (Fehlschlag bei Verstößen)
clang-format --dry-run --Werror src/**/*.{cpp,h}

Navigationsstrategie

Befolge für die meisten Aufgaben diesen Fortschritt:

1. Beginne mit Vorlagen: Durchsuche assets/configs/ nach einsatzbereiten Konfigurationen
2. Schnellreferenz: Überprüfe references/quick-reference.md für vollständige Konfigurationen mit Erklärungen
3. Kategorieanleitungen: Konsultiere references/01-09.md für spezifische Optionskategorien
4. CLI-Nutzung: Konsultiere references/cli-usage.md für Befehlszeilen- und Integrationsdetails
5. Vollständige Referenz: Verwende references/complete/ für erschöpfende Optionsdokumentation

Wenn du Code analysierst oder Fehler behebst, identifiziere den Formatierungsaspekt (Klammern, Abstände, Ausrichtung, etc.) und springe direkt zur relevanten Kategorieanleitung in references/.