CSpell

The CSPELL job runs spelling checks on the module's code, using cspell. This checks for spelling mistakes and unrecognized words and will give suggested corrections. The language is US English, the Drupal standard. CSPELL checks all words of length 4 or more, in comments, variable names and function names.

Your module does not need to have a .cspell.json configuration file, as a default one is used, based on the Drupal core file. This contains Drupal's two custom dictionaries and other standard dictionaries of programming terms.

Variable names and Function names

Variable names and function names that are all lower-case and consist of two or more words joined together are likely to be reported as unrecognized. It may be appropriate to change these to snake_case or lowerCamelCase to resolve the problem, because the name will be separated out into the individual words to be checked.

How do I ignore words that CSpell thinks are spelling mistakes?

When you have fixed any actual spelling errors, there are several ways to tell cspell not to report other words that it thinks are incorrect. You can use any combination of the following:

Short word list

If you only have a short list of words to ignore, and they are used in several files throughout the project, the simplest solution is provide a value for the _CSPELL_WORDS variable. For example:

variables:
  _CSPELL_WORDS: 'mycustomthing, madeupword'

The words should be comma-separated but each word does not need to be quoted individually. The list is not case-sensitive.

Custom project dictionary

If there are many words in your project that are invented or that are not included in the default dictionaries you can add a .cspell-project-words.txt file to your project. Each word should be on a separate line, and blank lines and comments starting with # are ignored. CSpell's Words List Syntax has more details.

Ignore words specific to one file

If a file contains some reported words that are only used in that file, instead of adding them to the project dictionary they can be listed at the top of the file. This is done by adding a special style of comment that CSpell will interpret. The format for a list of words is cspell:ignore mycustomthing madeupword

Disable spell checking on the next line

To disable all spell checking on the next line of a file add a comment cspell:disable-next-line

Disable spell checking for a block of lines

To disable all checking within a block of lines, add a comment cspell:disable at the start of the block and cspell:enable at the end. This can also be used to ignore the entire file, by adding cspell:disable at the top but not having any corresponding cspell:enable

For .md files you can use the comment style [//]: # cspell:disable and [//]: # cspell:enable

For .json files you can use the property name _comment which is ignored by json validation, so you would have "_comment": "cspell:disable", at the start and "_comment": "cspell:enable", at the end of the section to ignore.

Ignore entire paths

To ignore all files in a folder, add the path to the _CSPELL_IGNORE_PATHS variable. For example:

variables:
  _CSPELL_IGNORE_PATHS: 'tests/data/*, **/*.log'

The list should be comma-separated, but the paths do not need to be quoted individually.

Skip the entire job

It is possible to not run the cspell job at all, by adding a SKIP_CSPELL: "1" variable to your project's .gitlab-ci.yml. However, we do not recommend that you do this, but instead use the various methods above to maintain a green passing pipeline.

Prevent specific words being used in the project

CSpell can highlight and prevent the usage of words which exist in dictionaries. This can be required for a variety of reasons - coding standards consistency when more than one spelling exists, local preferences, stylistic choices, etc. Drupal Core has e-mail, grey and queuing in the list of flagged words, and these are also contained in the default configuration for contrib projects. Any usage of these should be replaced with email, gray and queueing. Core also has please as a flagword, but this has been removed from the default for contrib projects.

If your project needs to specify additional words to be flagged, set the variable _CSPELL_FLAGWORDS to a comma-separated list of words to flag. Like _CSPELL_WORDS the list does not need quotes and it is case-insensitive.

Commonly ignored files

Several files that are either very common or mandatory for all projects often need to be ignored. So by default, the cspell job is configured to ignore the following:

composer.*, license.*, copyright.*, maintainers.*, changelog.*,
**/.*.json, package.json, yarn.lock, phpstan*, .*ignore

The first five in this list will be ignored in all folders within the directory hierarchy. Name matching is not case-sensitive and all file extensions are included.

The variable _CSPELL_IGNORE_STANDARD_FILES (which defaults to 1) is used to control this. If you want these files to be checked and not ignored then you can set _CSPELL_IGNORE_STANDARD_FILES: '0'

List of unrecognized words

The cspell job log shows each of the unrecognized words, with the file name, line and column number, a short "context" showing a segment of the line, and a list of alternative suggestions. To assist with fixing the words, or adding them to your custom dictionary, a sorted list is of words is saved as an artifact called _cspell_unrecognized_words.txt. This file contains all unrecognized words found, including all versions where the case is different. However, the actual spell checking is set to non-case-sensitive by default, so you only need to add one version of each word to _CSPELL_WORDS or .cspell-project-words.txt.

Extra options

If there are extra options that you want to pass to the cspell executable command, specify these in the _CSPELL_EXTRA variable.

Full customization

For more advanced configuration, you can add a .cspell.json file to your project, which follows CSpell's configuration syntax. Start by downloading the generated _cspell_json.txt artifact from the cspell job, save it into your project as .cspell.json, and customize it to your needs.

Your customized file will work in addition to the values of _CSPELL_WORDS, _CSPELL_IGNORE_PATHS and _CSPELL_IGNORE_STANDARD_FILES so you do not need to include those values in your .cspell.json configuration. You can make changes to the paths to run cspell locally and the values will be modified in the gitlab cspell job to match what is needed when running a pipeline.