config.yml über die CodeCharter-CLI bearbeiten

Die Befehlsgruppe config liest und bearbeitet .codecharter/config.yml für dich. Jeder Schreibvorgang erhält deine Kommentare, die Schlüsselreihenfolge und die Formatierung, prüft die Änderung vor dem Schreiben und hinterlässt die Datei nie halb geschrieben.

codecharter config <unterbefehl> [argumente] [optionen]

Das Format der Konfigurationsdatei selbst (Profile, Parameter, Severities, Regel-Aktivierung und Pfad-Scopes) beschreibt Konfigurationsdatei. Diese Seite behandelt die Befehle, die sie verändern.

Konfiguration inspizieren

• codecharter config explain <pfad> zeigt die effektive Konfiguration für eine Quelldatei, samt der Schicht, aus der jeder Wert stammt. Mit --json gibt es maschinenlesbare Ausgabe.
• codecharter config validate prüft die Datei auf Strukturfehler, unbekannte Regeln, ungültige Parameterwerte und Einträge, die nie greifen.
• codecharter config schema gibt ein JSON-Schema für die Editor-Vervollständigung aus. Mit --out <datei> schreibst du es auf die Festplatte.
• codecharter config get <schlüssel> gibt den rohen Wert eines einzelnen Schlüssels aus.
• codecharter config list [abschnitt] gibt eine Übersicht aller Abschnitte aus oder die Einträge eines Abschnitts (profiles, params, overrides, ignore, include, exclude, scopes, coverage).

get erwartet einen punktierten Schlüssel: params.<regel>.<name>, overrides.<regel>.severity, profiles.<slug> oder einen der skalaren Coverage-Schlüssel coverage.minimum-percent, coverage.snippet-context-lines und coverage.max-parallel-test-projects. Mit --scope "<glob>" liest du aus dem Scope, dessen match diesem Glob entspricht, statt aus der Basisschicht.

Werte bearbeiten: set und unset

codecharter config set <schlüssel> <wert> [--scope <glob>] [--local] [--dry-run] [--rules <dir>]
codecharter config unset <schlüssel> [--local] [--dry-run]

set schreibt einen Parameter, einen Severity-Override oder eine Profil-Version:

codecharter config set params.cyclomatic-complexity.max 15
codecharter config set overrides.magic-number.severity warning
codecharter config set profiles.dotnet-base 1.4.2
codecharter config set coverage.minimum-percent 99.5

Der Wert wird vor dem Schreiben geprüft: eine unbekannte Regel, ein Parameter, den die Regel nicht anbietet, ein Wert außerhalb des erlaubten Bereichs oder eine ungültige Severity werden abgelehnt, und die Datei bleibt unverändert (Exit-Code 10). unset entfernt einen params- oder overrides-Eintrag wieder.

Parameterwerte werden gegen die Regeln geprüft, die die Config unter profiles: und rules: deklariert, also dieselben Quellen, die analyze liest. --rules fügt ein Verzeichnis mit .ccr- oder .cgr-Dateien hinzu. Ein nicht deklarierter rules-Ordner wird nicht gelesen.

Listen verwalten: add und remove

codecharter config add <abschnitt> [wert] [--in <ns>] [--match <glob>] [--path <datei>] [--scope <glob>] [--local] [--dry-run]
codecharter config remove <abschnitt> [wert] [--in <ns>] [--match <glob>] [--path <datei>] [--scope <glob>] [--local]

add und remove verwalten die listenwertigen Abschnitte:

codecharter config add exclude "**/Migrations/**"
codecharter config add profiles security@latest
codecharter config add ignore todo-comment --in Acme.Generated
codecharter config add include todo-comment --match "*Dto"
codecharter config add coverage.exclude "**/*.Designer.cs"
codecharter config add rules .codecharter/rules

rules deklariert ein lokales Regelverzeichnis, aufgelöst gegen das Repository-Root. Nur so kommt ein lokales Verzeichnis ohne --rules in einen Lauf (erfordert CodeCharter 1.6.4; config validate weist darauf hin, damit ältere CLIs, die den Schlüssel ignorieren würden, auffallen).

Bei ignore und include schränkt --in den Eintrag auf einen Namespace ein und --match auf Entitäten, deren gemeldeter Name einem Glob entspricht. Bei einem Typ, einer Methode, Property oder einem Field ist dieser Name vollqualifiziert (Namespace plus einfacher Name), und ein Muster ohne führendes * muss an der Namespace-Wurzel beginnen; Events und Findings auf Vorkommen-Ebene (Parameter, Member-Zugriffe und Ähnliches) werden stattdessen mit ihrem einfachen, unqualifizierten Namen gemeldet. Bei profiles verweist du mit --path auf eine lokale Bundle-Datei statt auf einen Slug. remove löscht den passenden Eintrag; ein mehrdeutiges Entfernen, das auf mehrere Einträge passt, wird als Nutzungsfehler gemeldet, statt zu raten.

Coverage-Schlüssel

Das Coverage-Gate konfigurierst du auf demselben Weg, mit zwei Unterschieden. Die drei skalaren Schlüssel minimum-percent, snippet-context-lines und max-parallel-test-projects laufen über set/unset/get, die beiden Glob-Listen dagegen als coverage.exclude und coverage.excluded-directories über add/remove. Und weil der Abschnitt repositoryweit gilt, wird --scope bei jedem Coverage-Schlüssel abgelehnt. --local, --dry-run, promote und demote verhalten sich wie überall sonst.

codecharter config set coverage.max-parallel-test-projects 1
codecharter config add coverage.excluded-directories "vendor/**"

config list coverage gibt die Schlüssel aus, die deine Datei tatsächlich setzt, die Skalare als schlüssel: wert und jeden Glob in einer eigenen exclude:- oder excluded-directories:-Zeile. In der Übersicht zählt der Abschnitt gesetzte Schlüssel statt Einträge, coverage: 2 bedeutet also, dass zwei der fünf Schlüssel konfiguriert sind. Ein nie gesetzter Schlüssel fehlt in der Ausgabe, statt mit seinem eingebauten Standardwert zu erscheinen.

Scopes und das lokale Overlay ansteuern

Zwei Optionen bestimmen, wohin ein Schreibvorgang geht; sie gelten für set, unset, add und remove:

• --scope "<glob>" schreibt in den Scope, dessen match diesem Glob entspricht, und legt den Scope am Ende der Datei an, falls er noch nicht existiert. Ohne diese Option gehen Schreibvorgänge in die Basisschicht.
• --local zielt auf .codecharter/config.local.yml (dein persönliches, lokales Overlay) statt auf die eingecheckte config.yml.

--dry-run gibt den Unified-Diff der geplanten Änderung aus und schreibt nichts. Kombiniere es mit jedem Schreibvorgang, um die Änderung vorab zu sehen.

Gerüst und Aufräumen: init und tidy

codecharter config init [--at <dir>] [--profiles <csv>] [--local] [--force] [--dry-run]
codecharter config tidy [--local] [--dry-run]

init erstellt eine minimale .codecharter/config.yml (nur version: 1). Mit --profiles "dotnet-base@1.4.2,security@latest" setzt du Startprofile, mit --at wählst du das Verzeichnis, mit --local legst du stattdessen das lokale Overlay an, und mit --force überschreibst du eine bestehende Datei.

init sorgt außerdem dafür, dass .codecharter/cache/ in der .gitignore steht (die Datei wird bei Bedarf angelegt, ein passender Eintrag ergänzt), damit die Disk-Caches mehrerer Tools – darunter der Bundle-Cache von restore und der Revisions-Snapshot-Cache von graph diff – nicht versehentlich eingecheckt werden. Ignoriert ein Repo bereits das gesamte .codecharter/-Verzeichnis oder enthält es den Eintrag schon, bleibt die Datei unverändert. Dieser Schritt ist Best-Effort: ein I/O-Fehler hier lässt init selbst nicht scheitern, da die Konfigurationsdatei bereits erfolgreich angelegt wurde.

tidy entfernt leere Abschnitte, die frühere Bearbeitungen hinterlassen haben, und hält die Datei sauber.

Das lokale Overlay: config local

codecharter config local clone [--force] [--dry-run]
codecharter config local diff
codecharter config local clear [schlüssel...] [--dry-run]

.codecharter/config.local.yml überschreibt config.yml auf deinem Rechner und wird nie eingecheckt (nimm es in .gitignore auf). Die Untergruppe local verwaltet es:

• clone kopiert die eingecheckte Konfiguration als Ausgangspunkt nach config.local.yml. --force überschreibt ein bestehendes Overlay.
• diff zeigt, was das Overlay aktuell überschreibt.
• clear entfernt bestimmte punktierte Schlüssel aus dem Overlay oder löscht die gesamte Overlay-Datei, wenn keine Schlüssel angegeben sind.

Einstellungen zwischen Schichten verschieben: promote und demote

codecharter config promote [schlüssel] [--all] [--keep] [--dry-run] [--rules <dir>]
codecharter config demote [schlüssel] [--all] [--dry-run] [--rules <dir>]

• promote verschiebt eine Einstellung aus deinem lokalen Overlay in die eingecheckte config.yml, wenn eine persönliche Anpassung zum Team-Standard werden soll. --keep kopiert statt zu verschieben (der Eintrag bleibt im Overlay), und --all befördert das gesamte Overlay und leert es danach.
• demote kopiert eine eingecheckte Einstellung in dein lokales Overlay, sodass du lokal davon abweichen kannst, ohne die geteilte Datei zu ändern. --all kopiert die gesamte eingecheckte Konfiguration ins Overlay.

Ein häufiges Muster: demote profiles.dotnet-base, gefolgt von set profiles.dotnet-base latest --local, pinnt das Team auf eine exakte Version, während du auf deinem Rechner die neueste verfolgst.

Exit-Codes

Die lesenden Befehle get und list verwenden:

• 0: Erfolg.
• 1: keine .codecharter/config.yml gefunden.
• 2: Nutzungsfehler (zum Beispiel ein nicht parsbarer Schlüssel).

Die bearbeitenden Befehle (set, unset, add, remove, init, tidy, die Untergruppe local, promote, demote) verwenden:

• 0: Erfolg, einschließlich --dry-run-Vorschauen.
• 2: Nutzungsfehler (falsche Argumente oder ein mehrdeutiges remove).
• 10: Validierungsfehler, die Änderung wurde abgelehnt und die Datei blieb unverändert.