Provenance

Every emitted Rule carries its source. This is exposed in the output, in the JSON API, and (optionally) inline as comments.

Source taxonomy

class RuleSource(StrEnum):
    TEMPLATE   = "template"   # bundled .gitignore template for a feature
    MINED      = "mined"      # rules_table.json entry
    USER_EXTRA = "user_extra" # passed via GenerateOptions(extras=[...])

These are also the section order in the rendered file (templates first, then mined, then user extras). The order is not configurable — it is the deterministic precedence used by stable dedupe.

Inline provenance

Pass include_provenance=True to annotate each rule:

from occam_gitignore_core import GenerateOptions
GenerateOptions(include_comments=True, include_provenance=True)

Output:

# Generated by occam-gitignore. Deterministic. Do not edit by hand.

# --- template ---
__pycache__/  # python
.venv/        # python
.DS_Store     # common

# --- mined ---
.env          # python

The suffix is # <feature-name> for template rules. Mined and user-extra rules attach their feature when one is recorded.

Why provenance matters

• Trust. A reviewer can verify that an unfamiliar pattern came from a trusted source and not from someone's improvisation.
• Diff diagnostics. When a .gitignore changes, provenance tells you whether the cause was a template update, a rules-table update, or a user override.
• Mining feedback. If a mined rule turns out to be a false positive, you know which feature group to investigate in rules_table.json.