Configuration file

CodeCharter reads a single configuration file, .codecharter/config.yml, from your repository. It controls which rule profiles apply, the values of tunable rule parameters, per-rule severities, which findings are switched on or off, and which paths are analysed. One file covers the whole repository, and path scopes let you vary the configuration for individual folders.

Location and discovery

Place the file at .codecharter/config.yml in your repository. When CodeCharter analyses a file, it looks for .codecharter/config.yml starting at the file's directory and walking up to the repository root, so a config at the root applies to everything beneath it.

An optional .codecharter/config.local.yml sits next to it for personal, machine-local overrides. It is never committed (add it to .gitignore) and takes precedence over config.yml. Use it to float your local rule versions or to quiet a rule on your machine without changing the shared configuration. CI, which never has this file, stays reproducible.

A complete example

version: 1

# Rule profiles to apply, newest-first. A bare slug or @latest floats to the
# newest published version; an exact version pins it. Platform profiles use the
# org/slug form. Use { path: ... } to load a local bundle instead of the portal.
profiles:
  - [email protected]
  - security@latest
  - acme/house-style@^2.1.0
  - { path: ./bundles/internal-rules.cgbundle }

# Values for tunable rule parameters, keyed by rule-slug.paramName.
params:
  cyclomatic-complexity.max: "15"
  method-length.maxLines: "60"

# Per-rule severity. Only severity can be overridden here.
overrides:
  magic-number:
    severity: warning
  empty-catch-block:
    severity: error

# Switch findings off. Optionally limit to a namespace (in:) or to entities
# whose name matches a glob (match:).
ignore:
  - rule: namespace-distance
    in: Acme.Generated
  - rule: todo-comment
  - rule: const-naming
    match: "*InstanceMemberBindingFlags"

# Switch a rule back on after it was ignored more broadly (e.g. in a scope).
include:
  - rule: todo-comment

# Paths excluded from analysis entirely (glob patterns).
exclude:
  - "**/tests/**"
  - "**/obj/**"
  - "**/Migrations/**"

# Folder-specific overrides. Each scope matches one or more path globs and may
# set any of the sections above; settings apply only to files the scope matches.
scopes:
  - match:
      - "src/Legacy/**"
    overrides:
      magic-number:
        severity: info
    ignore:
      - rule: cyclomatic-complexity

Sections

version

Required. The configuration format version. Use version: 1.

profiles

The rule profiles to apply. Each entry is either a slug reference or a local bundle path:

• [email protected] — an exact published version.
• security@latest or a bare security — floats to the newest published version, re-resolved when you run codecharter update.
• security@^2.1.0 / [email protected].* — a version range.
• acme/[email protected] — a platform profile, addressed as org/slug.
• { path: ./bundles/rules.cgbundle } — a local .cgbundle, not fetched from the portal.

params

Values for rule parameters that a rule exposes, keyed by rule-slug.paramName. Values are written as strings; CodeCharter validates them against each parameter's declared type and range. A rule that exposes no parameters, or a parameter name that does not exist, is reported by codecharter config validate.

overrides

Changes a rule's severity. The only field is severity, one of error, warning (or warn), or info. To switch a rule off entirely, use ignore rather than overrides.

ignore and include

ignore switches findings off; include switches them back on. Each entry targets a rule by slug and may narrow the target:

• in: Acme.Core — applies only to findings in that namespace or a namespace beneath it.
• match: "*Dto" — applies only to entities whose name matches the glob.

ignore and include share one activation signal that is evaluated in order: the base layer first, then each matching scope top to bottom. The last matching entry wins, so you can ignore a rule broadly and re-include it for a narrower path or namespace.

exclude

Glob patterns for paths that are dropped from analysis before any rule runs. exclude is additive: the base patterns and the patterns of every matching scope all apply.

scopes

Folder-specific configuration. Each scope has a match list of path globs and may contain any of params, overrides, ignore, include, and exclude. A scope's settings apply only to files it matches. Resolution is last-match-wins for params, overrides, and rule activation, anchored on the source file of the entity being evaluated; exclude is additive across all matching scopes.

Inspecting and validating the configuration

Three commands help you work with the file:

• codecharter config explain <path> shows the effective configuration for a given source file, including which layer (base or which scope) each value came from. Add --json for machine-readable output.
• codecharter config validate checks the file for structural errors, unknown rule ids, invalid parameter values, and entries that never match anything.
• codecharter config schema emits a JSON Schema for .codecharter/config.yml that editors can use for completion and validation. Pass --out <file> to write it to disk.

To edit the file from the command line instead of by hand — set parameters and severities, manage profiles and exclusions, scaffold the file, and sync the local overlay — use the config write commands. Every edit preserves your comments and formatting and is validated before it is written. See codecharter config.

Relationship to suppressions

ignore/exclude operate at the repository or folder level. To silence a single finding at the point in the code where it occurs, use an inline suppression comment instead — see Suppressions.