Configuration Reference

Folder hierarchy

For each source or header file in your compilation, .clang-rules files are loaded from the filesystem hierarchy. The most nested .clang-rules file overrides the severity of rules configured higher in the hierachy:

- Folder
  - .clang-rules         # Applies to declarations in 'File.cpp' and 'Header.h'
  - Subfolder
    - .clang-rules       # Applies to declarations in 'File.cpp' and 'Header.h'
    - File.cpp
    - AnotherSubfolder
      - .clang-rules     # Applies to declarations in 'Header.h', overriding severity levels in 'File.cpp'
      - Header.h

Multiple configurations in .clang-rules

Each .clang-rules file can have multiple configurations (YAML documents) inside it, where each document is separated by ---, like so:

Namespace: namespace-1
Rulesets:
- # ...
- # ...
Rules:
- # ...
- # ...

---

Namespace: namespace-2
Rulesets:
- # ...
Rules:
- # ...

---

Namespace: namespace-3
Rulesets:
- # ...
Rules:
- # ...
- # ...

Configuration file reference

Each configuration defines a namespace, zero or more rulesets and zero or more rules:

# When rules and rulesets are defined, they get this namespace applied to them 
# so that you can reference rules and rulesets across different documents without
# risk of name collision.
Namespace: unique-namespace
# Turn the experimental include-what-you-use analysis on or off. Omitting this setting
# inherits the setting from the parent .clang-rules file, or defaults to off if there
# isn't one.
IWYUAnalysis: true
# The list of rulesets that are defined in this namespace.
Rulesets:
- # The name of this ruleset being defined. For .clang-rules configurations in 
  # a different namespace, this could be referred to as 'unique-namespace/my-ruleset'.
  Name: my-ruleset
  # For rules referenced just by their name, they'll use this severity. If you don't
  # specify a 'Severity' option for a ruleset, it defaults to 'Warning'.
  # Values: 'Silence', 'Info', 'Warning' or 'Error'.
  Severity: Error
  # A list of rules that this ruleset activates. Rulesets in more deeply nested
  # .clang-rules files will override the severity of rules activated by .clang-rules
  # files higher in the filesystem hierarchy.
  Rules:
  - # Enable the 'my-rule' rule that is defined in this namespace (see below) at
    # the default severity of this ruleset.
    my-rule
  - # Enable the 'another-rule' rule that is defined in the 'other-namespace'
    # namespace (presumably in another .clang-rules file higher in the filesystem
    # hierarchy, or in another configuration in this same .clang-rules file).
    other-namespace/another-rule
  - # Enable the 'my-other-rule' that is defined in this namespace (see below),
    # but emit diagnostics as warnings instead of the default severity of this
    # ruleset.
    Name: my-other-rule
    # Values: 'Silence', 'Info', 'Warning' or 'Error'.
    Severity: Warning
  - # Enable the 'another-another-rule' that is defined in the 'other-namespace'
    # namespace, but emit diagnostics as warnings instead of the default severity
    # of this ruleset.
    Name: other-namespace/another-another-rule
    # Values: 'Silence', 'Info', 'Warning' or 'Error'.
    Severity: Warning
  # A list of other rulesets that this ruleset activates. The only rulesets that
  # make sense to reference in this option are rulesets that have 'DefineOnly: true'
  # (see below).
  Rulesets:
  - # Enable the 'my-other-ruleset' ruleset defined in this namespace (see below).
    my-other-ruleset
  - # Enable the 'another-ruleset' ruleset defined in the 'other-namespace' namespace.
    other-namespace/another-ruleset
  # By default rulesets are both defined and activated for the source and header files
  # in the directory and subdirectories that this .clang-rules file is located in. If
  # you want to define a ruleset, but only have it active for some subset of
  # subdirectories, you can set 'DefineOnly: true' and then use the 'Rulesets' option
  # of a ruleset in a .clang-rules file in a subdirectory to then activate it.
  DefineOnly: false
- # Define another ruleset.
  Name: my-other-ruleset
  # ...
# The list of rules that are defined in this namespace. Rules do
# not apply unless they're activated by a ruleset.
Rules:
- # The name of the rule being defined. For .clang-rules configurations in 
  # a different namespace, this could be referred to as 'unique-namespace/my-rule'.
  Name: my-rule
  # The Clang AST matcher expression. Refer to the 'Matcher Reference' on how 
  # to write these expressions.
  Matcher: |
    decl(has(decl().bind("another_hint"))).bind("callsite")
  # The compiler diagnostic message to emit at the callsite when this static
  # analysis rule matches.
  ErrorMessage: |
    this is the error message to emit as a diagnostic
  # The name of the bound node in the matcher which indicates the location to
  # emit the compiler diagnostic at.
  Callsite: callsite
  # Additional hint diagnostics to emit when this static analysis rule
  # matches. The key is the name of the bound node in the matcher and the
  # value is the diagnostic message to emit (at 'note' severity).
  Hints:
    another_hint: another diagnostic message to emit
  # If true, this rule only applies when the compilation triple targets
  # Windows. This can be used for rules which match on Windows-specific AST
  # nodes (such as '__declspec(dllexport)').
  WindowsOnly: true
  # If true, the AST of bound nodes in the AST matcher expression will be
  # dumped to the compiler console output when this rule matches. This can be
  # used to create and diagnose matcher expressions. The AST of bound nodes
  # will be dumped to compiler console output even if this rule is silenced,
  # so you should never leave this option turned on in configuration files 
  # committed to source control.
  Debug: false
- # Define another rule.
  Name: my-other-rule
  # ...