From d0f81dc972d4fc9862590daafb26ee03a2dbfda5 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 6 Oct 2025 16:16:10 -0500 Subject: [PATCH] docs(ref): Re-organize help more like cargo This should allow going into more detail --- docs/reference.md | 198 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 174 insertions(+), 24 deletions(-) diff --git a/docs/reference.md b/docs/reference.md index 6666a58b..6c50845d 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -13,35 +13,185 @@ Configuration is read from the following (in precedence order) exist, the config file will be skipped. - In `Cargo.toml`, the below fields must be under either `[workspace.metadata.typos]` or `[package.metadata.typos]` -### Config Fields +### Format -| Field | Argument | Format | Default | Description | -|------------------------|-------------------|--------|---------|-------------| -| files.binary | --binary | bool | false | Check binary files as text. | -| files.extend-exclude | --exclude | list of strings | \- | Typos-specific ignore globs (gitignore syntax). | -| \- | --force-exclude | bool | false | Respect excluded files even for paths passed explicitly. | -| files.ignore-hidden | --hidden | bool | true | Skip hidden files and directories. | -| files.ignore-files | --ignore | bool | true | Respect ignore files. | -| files.ignore-dot | --ignore-dot | bool | true | Respect .ignore files. | -| files.ignore-vcs | --ignore-vcs | bool | true | Respect ignore files in vcs directories. | -| files.ignore-global | --ignore-global | bool | true | Respect global ignore files. | -| files.ignore-parent | --ignore-parent | bool | true | Respect ignore files in parent directories. | -| default.binary | --binary | bool | false | Check binary files as text. | -| default.check-filename | \- | bool | true | Verify spelling in file names. | -| default.check-file | \- | bool | true | Verify spelling in files. | -| default.unicode | --unicode | bool | true | Allow unicode characters in identifiers (and not just ASCII). | -| default.locale | --locale | en, en-us, en-gb, en-ca, en-au | en | English dialect to correct to. | -| default.extend-ignore-re | \- | list of [regexes](https://docs.rs/regex/latest/regex/index.html#syntax) | \- | Custom uncorrectable sections (e.g. markdown code fences, PGP signatures, etc) | -| default.extend-identifiers | \- | table of strings | \- | Corrections for [identifiers](./design.md#identifiers-and-words). When the correction is blank, the identifier is never valid. When the correction is the key, the identifier is always valid. | -| default.extend-ignore-identifiers-re | \- | list of [regexes](https://docs.rs/regex/latest/regex/index.html#syntax) | \- | Pattern-match always-valid identifiers. | -| default.extend-words | \- | table of strings | \- | Corrections for [words](./design.md#identifiers-and-words). When the correction is blank, the word is never valid. When the correction is the key, the word is always valid. | -| default.extend-ignore-words-re | \- | list of [regexes](https://docs.rs/regex/latest/regex/index.html#syntax) | \- | Pattern-match always-valid words. Note: you must handle case insensitivity yourself. | -| type.\.\ | \ | \ | \ | See `default.` for child keys. Run with `--type-list` to see available ``s. | -| type.\.extend-glob | \- | list of strings | \- | File globs for matching ``. This is required when defining new file types. | +Summary of configuration (see below for details) +```toml +[files] +binary = false +extend-exclude = [] +ignore-hidden = true +ignore-files = true +ignore-dot = true +ignore-vcs = true +ignore-global = true +ignore-parent = true + +[default] +binary = false +check-filename = true +check-file = true +unicode=true +locale = "en" +extend-ignore-re = [] +extend-ignore-identifiers-re = [] +extend-ignore-words = [] + +[default.extend-words] + +[default.extend-identifiers] + +[type.NAME] +extend-glob = [] +# ... see `default` +``` Notes: - For the distinction between "words" and "identifiers", see [design](design.md#identifiers-and-words) +### Configuration keys + +#### `files.binary` + +- Type: `bool` +- Default: `false` +- CLI: `--binary` + +Check binary files as text. + +#### `files.extend-exclude` + +- Type: list of strings +- CLI: `--exclude` + +Typos-specific ignore globs (gitignore syntax) + +Note: the command-line overrides this by default. +See `--force-exclude` to ensure this field is always respected. + +#### `files.ignore-hidden` + +- Type: bool +- Default: true +- CLI: --hidden + +Skip hidden files and directories. + +#### `files.ignore-files` + +- Type: bool +- Default: true +- CLI: --ignore + +Respect ignore files. + +#### `files.ignore-dot` + +- Type: bool +- Default: true +- CLI: `--ignore-dot` + +Respect .ignore files. + +#### `files.ignore-vcs` +- Type: bool +- Default: true +- CLI: `--ignore-vcs` + +Respect ignore files in vcs directories. + +#### `files.ignore-global` + +- Type: bool +- Default: true +- CLI: `--ignore-global` + +Respect global ignore files. + +#### `files.ignore-parent` + +- Type: bool +- Default: true +- CLI: `--ignore-parent` + +Respect ignore files in parent directories. + +#### `default.binary` + +- Type: bool +- Default: false +- CLI: `--binary` + +Check binary files as text. + +#### `default.check-filename` + +- Type: bool +- Default: true + +Verify spelling in file names. + +#### `default.check-file` + +- Type: bool +- Default: true + +Verify spelling in files. + +#### `default.unicode` + +- Type: bool +- Default: true +- CLI: `--unicode` + +Allow unicode characters in identifiers (and not just ASCII). + +#### `default.locale` + +- Type: String (`en`, `en-us`, `en-gb`, `en-ca`, `en-au`) +- Default: `en` +- CLI: `--locale` + +English dialect to correct to. + +#### `default.extend-ignore-re` + +- Type: list of [regexes](https://docs.rs/regex/latest/regex/index.html#syntax) + +Custom uncorrectable sections (e.g. markdown code fences, PGP signatures, etc) + +#### `default.extend-identifiers` + +- Type: table of strings + +Corrections for [identifiers](./design.md#identifiers-and-words). When the correction is blank, the identifier is never valid. When the correction is the key, the identifier is always valid. + +#### `default.extend-ignore-identifiers-re` + +- Type: list of [regexes](https://docs.rs/regex/latest/regex/index.html#syntax) + +Pattern-match always-valid identifiers. + +#### `default.extend-words` + +- Type: table of strings + +Corrections for [words](./design.md#identifiers-and-words). When the correction is blank, the word is never valid. When the correction is the key, the word is always valid. + +#### `default.extend-ignore-words-re` + +- Type: list of [regexes](https://docs.rs/regex/latest/regex/index.html#syntax) + +Pattern-match always-valid words. Note: you must handle case insensitivity yourself. + +#### `type.NAME.extend-glob` + +- Type: list of strings + +File globs for matching `NAME`. This is required when defining new file types. + +Run with `--type-list` to see available `NAME`s. + ### Example configurations Common `extend-ignore-re`: