Globs
CSpell uses globs to decide which files to check and which settings apply to a file. The same glob can match different files depending on where it is used.
Where Globs Are Used
| Where | Matching | Used to |
|---|---|---|
Globs on the command line and files | strict | Search for the files to check. |
ignorePaths and --exclude | loose | Skip files. |
overrides[].filename | loose | Apply settings to the files that match. |
- Strict matching matches only what the glob says.
*and**do not match names that start with.. - Loose matching works like a
.gitignorefile. A glob can also match at any depth and match the contents of a folder, and*and**match names that start with..
Glob Syntax
*matches any part of a file or folder name.**matches any number of folders, including none.?matches one character.{md,txt}matches any one of the comma-separated choices.[abc]matches one of the characters.!(COMMIT_EDITMSG|HEAD)matches any name except the ones listed.- A leading
!negates a glob. What it does depends on the setting: see Negative Globs.
Write globs with / between folder names, also on Windows.
The Example Folder
The examples on this page use this folder as the root. Each file is listed with its full relative path.
README.md
.hidden.md
.git/config
.git/COMMIT_EDITMSG
docs/a.md
docs/.x.md
node_modules/x/a.md
sub/.git (a file, as in a git worktree)
sub/node_modules/y/b.md
test/a.md
a/test/b.md
Glob Roots
A glob is relative to a folder, its root.
- Globs on the command line and
--excludeglobs are relative to the current working folder, or to the folder given with--root. - A glob in a configuration file is relative to that file's
globRoot. By default,globRootis the folder that holds the configuration file, with these exceptions:- For a configuration file inside a
.vscodeor.configfolder, it is the folder above that one. - For a
.vscode/cspell.jsonwithout aversionfield, or a configuration with"version": "0.1", it is${cwd}.
- For a configuration file inside a
- A glob that starts with
/is tied to the root. InignorePaths,/testmatchestest/a.mdbut nota/test/b.md. - A glob that starts with
**/is tested against the file's full path, so folders above the root count. See A Project Inside anode_modulesFolder.
${cwd}
${cwd} stands for the current working folder.
- Set
globRootto${cwd}to make the globs in a configuration file relative to wherecspellruns, instead of to the configuration file. - Start a glob with
${cwd}to make that one glob relative to the current working folder:${cwd}/docs.
cspell.json
{
"globRoot": "${cwd}",
"ignorePaths": ["/docs"]
}
With this file in project/, running cspell "**" from project/ ignores project/docs. Running it from
project/sub/ ignores project/sub/docs instead.
Configuration Files Next to the Documents
For each file it checks, CSpell also loads the configuration file nearest that file. Its ignorePaths and
overrides apply to that file, relative to that configuration file's own globRoot. A sub/cspell.json with
"ignorePaths": ["/drafts"] skips the files in sub/drafts.
Strict Matching: the Command Line and files
The globs on the command line select the files to check: cspell "**/*.md". When there are none, CSpell uses files
from the configuration. A glob in files matches the same files as on the command line, except where noted.
cspell "*.md"checks only the Markdown files in the root, hereREADME.md.cspell "**/*.md"checks Markdown files at any depth, except names that start with.and files inside folders that start with..cspell docschecks all files in thedocsfolder. This works for any existing folder, such asdocs/api.cspell .checks all files.- A glob ending in
/**also matches a file with that name.cspell "**/.git/**"checks the filesub/.git. - On the command line, a glob that starts with
/is an absolute path. Infiles, a leading/ties the glob to the root. - A glob that starts with
!skips the files it matches, using loose matching.cspell "**/*.md" "!test"skips bothtest/a.mdanda/test/b.md. So does["**/*.md", "!test"]infiles.
Dot Files and Folders
By default, * and ** do not match names that start with ., such as .github or .hidden.md.
- Use
--doton the command line, or"enableGlobDot": truein the configuration, to include them. - A glob that names the dot explicitly matches without
--dot:cspell "**/.*"checks.hidden.md,docs/.x.md, andsub/.git. - Without
--dot, the search does not enter folders that start with.. A glob that starts with the folder's name still works:cspell ".git/**"checks the files in.git, butcspell "**/.git/**"checks only the filesub/.git.
--dot and enableGlobDot only change strict matching. Loose matching always matches dot files.
Loose Matching: ignorePaths, --exclude, and Overrides
ignorePaths, --exclude, and overrides[].filename use loose matching.
What Loose Matching Adds
| Glob | Examples | Matches |
|---|---|---|
No / | node_modules, *.md | The name at any depth, and everything inside a folder with that name. |
A / before the end | /src, lib/src, **/.git | The path, and everything inside a folder with that path. |
Ends with / | .git/, /src/, lib/src/ | Only the contents of the folder. A single name, such as .git/, matches at any depth. |
Ends with ** | node_modules/**, **/test/** | As written. |
As in strict matching, a glob ending in /** also matches a file with that name: **/test/** matches a file named
test.
In overrides, these extra matches can be disabled with
overrideGlobsMatchFilesOnly. With it enabled,
examples.ts matches only a file named examples.ts, not the files inside a folder with that name, and src/**
matches only the files inside src, not a file named src.
A consequence of these rules: an override with "filename": "**/.git" applies to the file sub/.git and also to
every file inside a .git folder. Use .git/ for the files inside .git folders only. To apply settings only to a
file named .git, see A File Named .git.
--exclude
Globs given with --exclude use loose matching, with these differences from ignorePaths:
- Without
--exclude, CSpell skipsnode_modules/**. That is only thenode_modulesfolder in the root. Any--excludereplaces this default. - A leading
/does not tie a name without other slashes to the root:--exclude /testskips bothtest/a.mdanda/test/b.md.--exclude /test/skips onlytest/a.md. - A glob that matches at any depth is tested against the full path, as if it started with
**/. This applies tonode_modules,node_modules/,/**/node_modules/**, and${cwd}/**/node_modules/**.
What Each Glob Matches
The files each glob matches in the example folder, without --dot. The ignorePaths column
also applies to overrides[].filename.
| Glob | Command line and files | ignorePaths and overrides | --exclude |
|---|---|---|---|
*.md | README.md | All .md files | Same as ignorePaths |
**/*.md | All .md files except .hidden.md and docs/.x.md | All .md files | Same as ignorePaths |
docs | docs/a.md | docs/a.md, docs/.x.md | Same as ignorePaths |
test | test/a.md | test/a.md, a/test/b.md | Same as ignorePaths |
/test | Nothing | test/a.md | test/a.md, a/test/b.md |
test/ | test/a.md | test/a.md, a/test/b.md | Same as ignorePaths |
/test/ | Nothing on the command line, test/a.md in files | test/a.md | Same as ignorePaths |
test/** | test/a.md | test/a.md | Same as ignorePaths |
**/test/** | test/a.md, a/test/b.md | test/a.md, a/test/b.md | Same as ignorePaths |
node_modules | node_modules/x/a.md | node_modules/x/a.md, sub/node_modules/y/b.md | Same as ignorePaths |
node_modules/ | node_modules/x/a.md | node_modules/x/a.md, sub/node_modules/y/b.md | Same as ignorePaths |
node_modules/** | node_modules/x/a.md | node_modules/x/a.md | Same as ignorePaths |
**/node_modules/** | node_modules/x/a.md, sub/node_modules/y/b.md | node_modules/x/a.md, sub/node_modules/y/b.md | Same as ignorePaths |
.git | .git/config, .git/COMMIT_EDITMSG | .git/config, .git/COMMIT_EDITMSG, sub/.git | Same as ignorePaths |
.git/ | .git/config, .git/COMMIT_EDITMSG | .git/config, .git/COMMIT_EDITMSG | Same as ignorePaths |
.git/** | .git/config, .git/COMMIT_EDITMSG | .git/config, .git/COMMIT_EDITMSG | Same as ignorePaths |
**/.git | sub/.git | .git/config, .git/COMMIT_EDITMSG, sub/.git | Same as ignorePaths |
**/.git/** | sub/.git | .git/config, .git/COMMIT_EDITMSG, sub/.git | Same as ignorePaths |
**/.git/* | Nothing | .git/config, .git/COMMIT_EDITMSG | Same as ignorePaths |
** | All files except .hidden.md, docs/.x.md, sub/.git, and the files in .git | All files | Same as ignorePaths |
Negative Globs
A glob that starts with ! behaves differently in each setting.
- On the command line and in
files, it skips the files it matches:cspell "**/*.md" "!test". See Strict Matching. - In
ignorePathsand--exclude, it is not used. CSpell warns, for exampleNegative glob exclusions are not supported: !.git/COMMIT_EDITMSG, and applies the other globs. - In
overrides[].filename, it removes files from the match. When several globs match a file, the last one wins:["**/*.md", "!docs/**"]matches every Markdown file outsidedocs.
How CSpell Selects the Files to Check
Resolving the Configuration
CSpell first resolves the configuration: the configuration file it starts with, the files it imports, and the command-line options. Loading Configuration explains where the configuration file comes from.
Finding Files
The resolved configuration is used to find files.
- The globs come from the command line, or from
fileswhen there are none. - Files and folders that match
ignorePathsor--excludeare skipped. CSpell does not look inside a skipped folder, so a glob that names a file inside one finds nothing.
Checking Each File
Before checking a file, CSpell loads the configuration file nearest it: the first one found in the file's folder or
the folders above it. Its ignorePaths can still skip the file, and so can an override that sets "enabled": false.
--no-config-search turns this off.
Files given with --file, --files, or --file-list are not searched for. They are still filtered:
- by the globs on the command line, or by
fileswhen there are none; - by
ignorePathsand--exclude; - by the configuration file nearest each file, as above.
Use --force-check to check them anyway.
--fileand--filescannot be combined with globs on the command line.--file-listcan be. The globs then filter the list.--force-checkcannot be combined with globs on the command line.
Recipes
Ignore node_modules
cspell.json
{
"ignorePaths": ["node_modules/"]
}
This skips the contents of every node_modules folder under the root. Without it, CSpell skips only the
node_modules folder in the root, and only when no --exclude is given.
A Project Inside a node_modules Folder
A glob that starts with **/ is tested against the full path. When the root itself is inside a node_modules
folder, for example when checking an installed package, **/node_modules/** matches every file:
$ cd node_modules/my-package
$ cspell "**" # with "ignorePaths": ["**/node_modules/**"]
No files found to check.
These globs skip only node_modules folders under the root, and keep the files in node_modules/my-package:
node_modules/node_modules/**/node_modules/**${cwd}/**/node_modules/**
--exclude treats some of these globs differently. --exclude node_modules/ and
--exclude /**/node_modules/** also report No files found to check. --exclude /node_modules keeps the files in
node_modules/my-package and skips the node_modules folders under it.
Ignore .git but Check the Commit Message
A commit-msg git hook can check the message with cspell .git/COMMIT_EDITMSG. If ignorePaths contains .git,
.git/, or .git/**, that command reports No files found to check.
Ignore everything in .git except the commit message:
cspell.json
{
"ignorePaths": [".git/!(COMMIT_EDITMSG)"]
}
cspell .git/COMMIT_EDITMSG then checks the message, and cspell --dot "**" skips the rest of .git.
A File Named .git
In a git worktree or a submodule, .git is a file instead of a folder.
- On the command line and in
files,**/.gitmatches only files named.git. - In
ignorePathsand overrides,.gitand**/.gitmatch files named.gitand everything inside.gitfolders..git/matches only what is inside.gitfolders. - In an override, a negative glob limits the match to files named
.git:
cspell.json
{
"overrides": [
{
"filename": ["**/.git", "!.git/"],
"enabled": false
}
]
}
With overrideGlobsMatchFilesOnly enabled, .git in an
override matches only files named .git:
cspell.json
{
"features": {
"overrideGlobsMatchFilesOnly": true
},
"overrides": [
{
"filename": ".git",
"enabled": false
}
]
}