Fix common misspellings in text files. It's designed primarily for checking misspelled words in source code, but it can be used with other files as well.
- GitHub project
- Mailing list: <[email protected]> with web archives/interface here
- Repository
- Releases
Python 3.5 or above.
You can use pip
to install codespell with e.g.:
pip install codespell
For more in depth info please check usage with codespell -h
.
Some noteworthy flags:
codespell -w, --write-changes
The -w
flag will actually implement the changes recommended by codespell. Not running with -w
flag is the same as with doing a dry run. It is recommended to run this with the -i
or --interactive
flag.:
codespell -I FILE, --ignore-words=FILE
The -I
flag can be used for a list of certain words to allow that are in the codespell dictionaries. The format of the file is one word per line. Invoke using: codespell -I path/to/file.txt
to execute codespell referencing said list of allowed words. Important note: The list passed to -I
is case-sensitive based on how it is listed in the codespell dictionaries.
codespell -L word1,word2,word3,word4
The -L
flag can be used to allow certain words that are comma-separated placed immediately after it. Important note: The list passed to -L
is case-sensitive based on how it is listed in the codespell dictionaries.
codespell -S, --skip=
Comma-separated list of files to skip. It accepts globs as well. Examples:
- to skip .eps & .txt files, invoke
codespell --skip="*.eps,*.txt"
- to skip directories, invoke
codespell --skip="./src/3rd-Party,./src/Test"
Useful commands:
codespell -d -q 3 --skip="*.po,*.ts,./src/3rdParty,./src/Test"
List all typos found except translation files and some directories. Display them without terminal colors and with a quiet level of 3.
codespell -i 3 -w
Run interactive mode level 3 and write changes to file.
We ship a dictionary that is an improved version of the one available on Wikipedia after applying them in projects like Linux Kernel, EFL, oFono among others. You can provide your own version of the dictionary, but patches for new/different entries are very welcome.
Want to know if a word you're proposing exists in codespell already? It is possible to test a word against the current dictionary that exists in codespell_lib/data/dictionary.txt
via:
echo "word" | codespell - echo "1stword,2ndword" | codespell -
Command line options can also be specified in a config file.
When running codespell
, it will check in the current directory for a file
named setup.cfg
or .codespellrc
(or a file specified via --config
),
containing an entry named [codespell]
. Each command line argument can
be specified in this file (without the preceding dashes), for example:
[codespell] skip = *.po,*.ts,./src/3rdParty,./src/Test count = quiet-level = 3
This is equivalent to running:
codespell --quiet-level 3 --count --skip "*.po,*.ts,./src/3rdParty,./src/Test"
Any options specified in the command line will override options from the config file.
The format of the dictionary was influenced by the one it originally came from, i.e. from Wikipedia. The difference is how multiple options are treated and that the last argument is the reason why a certain entry could not be applied directly, but instead be manually inspected. E.g.:
Simple entry: one wrong word / one suggestion:
calulated->calculated
Entry with more than one suggested fix:
fiel->feel, field, file, phial,
Note the last comma! You need to use it, otherwise the last suggestion will be discarded (see below for why). When there is more than one suggestion, an automatic fix is not possible and the best we can do is to give the user the file and line where the error occurred as well as the suggestions.
Entry with one word, but with automatically fix disabled:
clas->class, disabled because of name clash in c++
Note that there isn't a comma in the end of the line. The last argument is treated as the reason why a suggestion cannot be automatically applied.
You can install required dependencies for development by running the following within a checkout of the codespell source:
pip install -e ".[dev]"
To run tests against the codebase run:
make check
If you have a suggested typo that you'd like to see merged please follow these steps:
Make sure you read the instructions mentioned in the
Dictionary format
section above to submit correctly formatted entries.Sort the dictionary. This is done by invoking (in the top level directory of
codespell/
):make check-dictionaries
If the make script finds that you need to sort the dictionary, please then run:
make sort-dictionaries
Only after this process is complete do we recommend you submit the PR.
Important Notes:
- If the dictionary is submitted without being pre-sorted the PR will fail via TravisCI.
- Not all PRs will be merged. This is pending on the discretion of the devs, maintainers, and the community.
To stay current with codespell developments it is possible to build codespell from GitHub via:
pip install --upgrade git+https://github.com/codespell-project/codespell.git
Important Notes:
Sometimes installing via
pip
will complain about permissions. If this is the case then run withpip install --user --upgrade git+https://github.com/codespell-project/codespell.git
It has been reported that after installing from
pip
, codespell can't be located. Please check the $PATH variable to see if~/.local/bin
is present. If it isn't then add it to your path.If you decide to install via
pip
then be sure to remove any previously installed versions of codespell (via your platform's preferred app manager).
In the scenario where the user prefers not to follow the development version of codespell yet still opts to benefit from the frequently updated dictionary.txt file, we recommend running a simple set of commands to achieve this
wget https://raw.githubusercontent.com/codespell-project/codespell/master/codespell_lib/data/dictionary.txt codespell -D dictionary.txt
The above simply downloads the latest dictionary.txt
file and then by utilizing the -D
flag allows the user to specify the freshly downloaded dictionary.txt
as the custom dictionary instead of the default one.
The Python script codespell
with its library codespell_lib
is available
with the following terms:
(tl;dr: GPL v2)
Copyright (C) 2010-2011 Lucas De Marchi <[email protected]>
Copyright (C) 2011 ProFUSION embedded systems
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, see <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>.
dictionary.txt
and the other dictionary_*.txt
files are a derived work of
English Wikipedia and are released under the Creative Commons
Attribution-Share-Alike License 3.0
http://creativecommons.org/licenses/by-sa/3.0/