Spell Checking

Installation

Basic Usage

Example: recursively spell check all JavaScript files in src

JavaScript files

cspell "src/**/*.js"
# or
cspell lint "src/**/*.js"

Check everything

cspell "**"

Adding CSpell to an existing project

In the steps below we will create a cspell configuration file and setup a single custom dictionary for the project.

Steps:

Create a configuration file
Add words to the project dictionary

1. Create a configuration file.

CSpell can use JSON, Yaml, and JavaScript files for configuration. It automatically searches for one of the following: cspell.json, cspell.config.yaml, cspell.config.cjs.

For now choose to use either JSON or Yaml. Below are examples of each that include a custom dictionary definition. Both of them are equivalent. If you have both, CSpell will look for the .json file first.

cspell.json

{
  "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
  "version": "0.2",
  "dictionaryDefinitions": [
    {
      "name": "project-words",
      "path": "./project-words.txt",
      "addWords": true
    }
  ],
  "dictionaries": ["project-words"],
  "ignorePaths": ["node_modules", "/project-words.txt"]
}

cspell.config.yaml

---
$schema: https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json
version: '0.2'
dictionaryDefinitions:
  - name: project-words
    path: './project-words.txt'
    addWords: true
dictionaries:
  - project-words
ignorePaths:
  - 'node_modules'
  - '/project-words.txt'

These configuration files do three things:

Define the custom dictionary project-words.
Tell the spell checker to use the custom dictionary.
Tell the spell checker to ignore any files inside of node_modules and the file project-words.txt.

2. Add words to the project dictionary

It might take a few iterations to get fully setup, but the process in the same.

Steps:

Create the dictionary file
```
touch project-words.txt
```
Choose a set of files to start with, like all Markdown files, **/*.md and run the spell checker.
```
cspell "**/*.md"
```
Look for any directories that need to be ignored and add them to ignorePaths. Example:
- "bin" - to ignore any directory / file called bin.
- "translations/**" - to ignore all files under the translations directory.
- "packages/*/dist" - to ignore the dist directory in each package.
Once you have finished identifying directories and files to be ignored, it is now time to add words to the custom dictionary.

Have CSpell populate it with the words from your project.

echo "# New Words" >> project-words.txt
cspell --words-only --unique "**/*.md" | sort --ignore-case >> project-words.txt

This will append all new issues to the end of project-words.txt

Review the words in project-words.txt to check for any actual misspellings and remove them (the spell checker already thinks they are wrong).

Fix spelling issues.

To show the issues and suggestions, use:

cspell --no-progress --show-suggestions --show-context "**/*.md"

Repeat the process with the other file types you want to check.

3. Fine-tuning

The following resources can help you with fine-tuning your configurations:

Help

Command: `lint` – Spell Checking

The lint command is used for spell checking files.

Help

cspell lint --help

Options

Usage: cspell lint [options] [globs...] [file://<path> ...] [stdin[://<path>]]

Patterns:
 - [globs...]            Glob Patterns
 - [stdin]               Read from "stdin" assume text file.
 - [stdin://<path>]      Read from "stdin", use <path> for file type and config.
 - [file://<path>]       Check the file at <path>

Examples:
    cspell .                        Recursively check all files.
    cspell lint .                   The same as "cspell ."
    cspell "*.js"                   Check all .js files in the current directory
    cspell "**/*.js"                Check all .js files recursively
    cspell "src/**/*.js"            Only check .js under src
    cspell "**/*.txt" "**/*.js"     Check both .js and .txt files.
    cspell "**/*.{txt,js,md}"       Check .txt, .js, and .md files.
    cat LICENSE | cspell stdin      Check stdin
    cspell stdin://docs/doc.md      Check stdin as if it was "./docs/doc.md"

Check spelling

Options:
  -c, --config <cspell.json>   Configuration file to use.  By default cspell
                               looks for cspell.json in the current directory.
  -v, --verbose                Display more information about the files being
                               checked and the configuration.
  --locale <locale>            Set language locales. i.e. "en,fr" for English
                               and French, or "en-GB" for British English.
  --language-id <language>     Force programming language for unknown
                               extensions. i.e. "php" or "scala"
  --words-only                 Only output the words not found in the
                               dictionaries.
  -u, --unique                 Only output the first instance of a word not
                               found in the dictionaries.
  -e, --exclude <glob>         Exclude files matching the glob pattern. This
                               option can be used multiple times to add
                               multiple globs.
  --file-list <path or stdin>  Specify a list of files to be spell checked. The
                               list is filtered against the glob file patterns.
                               Note: the format is 1 file path per line.
  --file [file...]             Specify files to spell check. They are filtered
                               by the [globs...].
  --no-issues                  Do not show the spelling errors.
  --no-progress                Turn off progress messages
  --no-summary                 Turn off summary message in console.
  -s, --silent                 Silent mode, suppress error messages.
  --no-exit-code               Do not return an exit code if issues are found.
  --quiet                      Only show spelling issues or errors.
  --fail-fast                  Exit after first file with an issue or error.
  -r, --root <root folder>     Root directory, defaults to current directory.
  --no-relative                Issues are displayed with absolute path instead
                               of relative to the root.
  --show-context               Show the surrounding text around an issue.
  --show-suggestions           Show spelling suggestions.
  --no-show-suggestions        Do not show spelling suggestions or fixes.
  --no-must-find-files         Do not error if no files are found.
  --cache                      Use cache to only check changed files.
  --no-cache                   Do not use cache.
  --cache-reset                Reset the cache file.
  --cache-strategy <strategy>  Strategy to use for detecting changed files.
                               (choices: "metadata", "content")
  --cache-location <path>      Path to the cache file or directory. (default:
                               ".cspellcache")
  --dot                        Include files and directories starting with `.`
                               (period) when matching globs.
  --gitignore                  Ignore files matching glob patterns found in
                               .gitignore files.
  --no-gitignore               Do NOT use .gitignore files.
  --gitignore-root <path>      Prevent searching for .gitignore files past
                               root.
  --validate-directives        Validate in-document CSpell directives.
  --no-validate-directives     Do not validate in-document CSpell directives.
  --no-color                   Turn off color.
  --color                      Force color.
  --no-default-configuration   Do not load the default configuration and
                               dictionaries.
  --debug                      Output information useful for debugging
                               cspell.json files.
  --reporter <module|path>     Specify one or more reporters to use.
  -h, --help                   display help for command

More Examples:

    cspell "**/*.js" --reporter @cspell/cspell-json-reporter
        This will spell check all ".js" files recursively and use
        "@cspell/cspell-json-reporter".

    cspell . --reporter default
        This will force the default reporter to be used overriding
        any reporters defined in the configuration.

    cspell . --reporter ./<path>/reporter.cjs
        Use a custom reporter. See API for details.

    cspell "*.md" --exclude CHANGELOG.md --files README.md CHANGELOG.md
        Spell check only check "README.md" but NOT "CHANGELOG.md".

    cspell "/*.md" --no-must-find-files --files $FILES
        Only spell check the "/*.md" files in $FILES,
        where $FILES is a shell variable that contains the list of files.

References:
    https://cspell.org
    https://github.com/streetsidesoftware/cspell

Spell Checking

Installation

Basic Usage

Adding CSpell to an existing project

1. Create a configuration file.

2. Add words to the project dictionary

3. Fine-tuning

Help

Command: lint – Spell Checking

Help

Options

Command: `lint` – Spell Checking