From 414bb96ebb75270f9dec0b29a0bbe1f2c7df2e4c Mon Sep 17 00:00:00 2001
From: mit-d <derekmttn@gmail.com>
Date: Sat, 28 Feb 2026 12:58:14 -0700
Subject: [PATCH] docs: document per-file overrides in README and man page

Also exclude tests/fixtures/ from mypy (Trojan Source fixtures).
---
 CHANGELOG.md         | 13 +++++++++++++
 README.md            | 25 ++++++++++++++++++++++++
 docs/check-unicode.1 | 45 +++++++++++++++++++++++++++++++++++++++-----
 pyproject.toml       |  3 +++
 4 files changed, 81 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 43ac5e4..9ba7db8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,18 @@
 # Changelog
 
+## Unreleased
+
+### Docs
+
+- Document per-file `[[tool.check-unicode.overrides]]` in README and man page
+- Update man page version to 0.4.0 and fix stale pre-commit `rev`
+- Add man page to `bump-my-version` files list
+
+### Fixed
+
+- Exclude `tests/fixtures/` from mypy (intentionally malformed Trojan Source
+  files)
+
 ## 0.4.0 - 2026-02-28
 
 ### Added
diff --git a/README.md b/README.md
index e1a16ac..a5b82fa 100644
--- a/README.md
+++ b/README.md
@@ -96,6 +96,31 @@ check-confusables = true
 severity = "error"
 ```
 
+### Per-file overrides
+
+Use `[[tool.check-unicode.overrides]]` to apply different settings per file
+pattern. Each entry requires a `files` key with a list of glob patterns and can
+set any of the options above.
+
+Allow-lists (`allow-codepoints`, `allow-ranges`, `allow-categories`,
+`allow-printable`, `allow-scripts`) are **additive** -- they merge with the
+global config. `severity` and `check-confusables` **replace** the global value
+for matching files.
+
+```toml
+# Relax rules for documentation
+[[tool.check-unicode.overrides]]
+files = ["docs/*.md", "*.rst"]
+allow-printable = true
+severity = "warning"
+
+# Allow non-Latin scripts in i18n files
+[[tool.check-unicode.overrides]]
+files = ["i18n/**"]
+allow-scripts = ["Cyrillic", "Han"]
+check-confusables = false
+```
+
 ## Output
 
 ```text
diff --git a/docs/check-unicode.1 b/docs/check-unicode.1
index 019edb7..c315d80 100644
--- a/docs/check-unicode.1
+++ b/docs/check-unicode.1
@@ -1,6 +1,6 @@
 .\" Man page for check-unicode
 .\" Generate with: man ./docs/check-unicode.1
-.TH CHECK\-UNICODE 1 "2026-02-20" "check-unicode 0.2.0" "User Commands"
+.TH CHECK\-UNICODE 1 "2026-02-28" "check-unicode 0.4.0" "User Commands"
 .
 .SH NAME
 check\-unicode \- detect and fix non\-ASCII Unicode characters in text files
@@ -199,13 +199,48 @@ severity          = "error"
 exclude\-patterns  = ["*.min.js", "vendor/*"]
 .RE
 .fi
+.PP
+Per\-file overrides can be added with
+.B [[tool.check\-unicode.overrides]]
+sections.
+Each entry requires a
+.B files
+key containing a list of glob patterns.
+Allow\-list options
+.RB ( allow\-codepoints ", " allow\-ranges ", " allow\-categories ", "
+.BR allow\-printable ", " allow\-scripts )
+are
+.B additive
+\(em they merge with the global config.
+.B severity
+and
+.B check\-confusables
+.B replace
+the global value for matching files.
+.PP
+.nf
+.RS
+[[tool.check\-unicode.overrides]]
+files             = ["docs/*.md", "*.rst"]
+allow\-printable   = true
+severity          = "warning"
+
+[[tool.check\-unicode.overrides]]
+files             = ["i18n/**"]
+allow\-scripts     = ["Cyrillic", "Han"]
+check\-confusables = false
+.RE
+.fi
 .
 .SH EXIT CODES
 .TP
 .B 0
-No findings were detected, or
-.B \-\-severity=warning
-was used.
+No findings were detected, or all findings came from files whose effective
+severity is
+.BR warning
+(set globally via
+.B \-\-severity
+or per\-file via overrides).
 .TP
 .B 1
 Non\-ASCII findings were detected, or files were modified in
@@ -331,7 +366,7 @@ Use with pre\-commit:
 .RS
 repos:
   \- repo: https://github.com/mit\-d/check\-unicode
-    rev: v0.2.0
+    rev: v0.4.0
     hooks:
       \- id: check\-unicode
       # or for auto\-fix:
diff --git a/pyproject.toml b/pyproject.toml
index d4f84b1..5f52a0d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -70,8 +70,11 @@ files = [
   { filename = "src/check_unicode/__init__.py" },
   { filename = "CHANGELOG.md", search = "## Unreleased", replace = "## {new_version} - {now:%Y-%m-%d}" },
   { filename = "README.md", search = "rev: v{current_version}", replace = "rev: v{new_version}" },
+  { filename = "docs/check-unicode.1", search = "check-unicode {current_version}", replace = "check-unicode {new_version}" },
+  { filename = "docs/check-unicode.1", search = "rev: v{current_version}", replace = "rev: v{new_version}" },
 ]
 
 [tool.mypy]
 python_version = "3.11"
 strict = true
+exclude = [ "tests/fixtures/" ]