1codespell
2=========
3
4Fix common misspellings in text files. It's designed primarily for checking
5misspelled words in source code, but it can be used with other files as well.
6
7Useful links
8------------
9
10* `GitHub project <https://github.com/codespell-project/codespell>`_
11
12* Mailing list: <codespell@googlegroups.com> with web archives/interface
13 `here <https://groups.google.com/forum/?fromgroups#!forum/codespell>`_
14
15* `Repository <https://github.com/codespell-project/codespell>`_
16
17* `Releases <https://github.com/codespell-project/codespell/releases>`_
18
19Requirements
20------------
21
22Python 3.5 or above.
23
24Installation
25------------
26
27You can use ``pip`` to install codespell with e.g.::
28
29 pip install codespell
30
31Usage
32-----
33
34For more in depth info please check usage with ``codespell -h``.
35
36Some noteworthy flags::
37
38 codespell -w, --write-changes
39
40The ``-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.::
41
42 codespell -I FILE, --ignore-words=FILE
43
44The ``-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. ::
45
46 codespell -L word1,word2,word3,word4
47
48The ``-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. ::
49
50 codespell -S, --skip=
51
52Comma-separated list of files to skip. It accepts globs as well. Examples:
53
54* to skip .eps & .txt files, invoke ``codespell --skip="*.eps,*.txt"``
55
56* to skip directories, invoke ``codespell --skip="./src/3rd-Party,./src/Test"``
57
58
59Useful commands::
60
61 codespell -d -q 3 --skip="*.po,*.ts,./src/3rdParty,./src/Test"
62
63List all typos found except translation files and some directories.
64Display them without terminal colors and with a quiet level of 3. ::
65
66 codespell -i 3 -w
67
68Run interactive mode level 3 and write changes to file.
69
70We ship a collection of dictionaries that are an improved version of the one available
71`on Wikipedia <https://en.wikipedia.org/wiki/Wikipedia:Lists_of_common_misspellings/For_machines>`_
72after applying them in projects like Linux Kernel, EFL, oFono among others.
73You can provide your own version of the dictionary, but patches for
74new/different entries are very welcome.
75
76Want to know if a word you're proposing exists in codespell already? It is possible to test a word against the current set dictionaries that exist in ``codespell_lib/data/dictionary*.txt`` via::
77
78 echo "word" | codespell -
79 echo "1stword,2ndword" | codespell -
80
81You can select the optional dictionaries with the ``--builtin`` option.
82
83Using a config file
84-------------------
85
86Command line options can also be specified in a config file.
87
88When running ``codespell``, it will check in the current directory for a file
89named ``setup.cfg`` or ``.codespellrc`` (or a file specified via ``--config``),
90containing an entry named ``[codespell]``. Each command line argument can
91be specified in this file (without the preceding dashes), for example::
92
93 [codespell]
94 skip = *.po,*.ts,./src/3rdParty,./src/Test
95 count =
96 quiet-level = 3
97
98This is equivalent to running::
99
100 codespell --quiet-level 3 --count --skip "*.po,*.ts,./src/3rdParty,./src/Test"
101
102Any options specified in the command line will *override* options from the
103config file.
104
105Dictionary format
106-----------------
107
108The format of the dictionaries was influenced by the one they originally came from,
109i.e. from Wikipedia. The difference is how multiple options are treated and
110that the last argument is an optional reason why a certain entry could not be
111applied directly, but should instead be manually inspected. E.g.:
112
1131. Simple entry: one wrong word / one suggestion::
114
115 calulated->calculated
116
1172. Entry with more than one suggested fix::
118
119 fiel->feel, field, file, phial,
120
121 Note the last comma! You need to use it, otherwise the last suggestion
122 will be discarded (see below for why). When there is more than one
123 suggestion, an automatic fix is not possible and the best we can do is
124 to give the user the file and line where the error occurred as well as
125 the suggestions.
126
1273. Entry with one word, but with automatic fix disabled::
128
129 clas->class, disabled because of name clash in c++
130
131 Note that there isn't a comma at the end of the line. The last argument is
132 treated as the reason why a suggestion cannot be automatically applied.
133
134 There can also be multiple suggestions but any automatic fix will again be
135 disabled::
136
137 clas->class, clash, disabled because of name clash in c++
138
139Development Setup
140-----------------
141
142You can install required dependencies for development by running the following within a checkout of the codespell source::
143
144 pip install -e ".[dev]"
145
146To run tests against the codebase run::
147
148 make check
149
150Sending Pull Requests
151---------------------
152
153If you have a suggested typo that you'd like to see merged please follow these steps:
154
1551. Make sure you read the instructions mentioned in the ``Dictionary format`` section above to submit correctly formatted entries.
156
1572. Choose the correct dictionary file to add your typo to. See `codespell --help` for explanations of the different dictionaries.
158
1593. Sort the dictionaries. This is done by invoking (in the top level directory of ``codespell/``)::
160
161 make check-dictionaries
162
163 If the make script finds that you need to sort a dictionary, please then run::
164
165 make sort-dictionaries
166
1674. Only after this process is complete do we recommend you submit the PR.
168
169**Important Notes:**
170
171* If the dictionaries are submitted without being pre-sorted the PR will fail via our various CI tools.
172* Not all PRs will be merged. This is pending on the discretion of the devs, maintainers, and the community.
173
174Updating
175--------
176
177To stay current with codespell developments it is possible to build codespell from GitHub via::
178
179 pip install --upgrade git+https://github.com/codespell-project/codespell.git
180
181**Important Notes:**
182
183* Sometimes installing via ``pip`` will complain about permissions. If this is the case then run with ::
184
185 pip install --user --upgrade git+https://github.com/codespell-project/codespell.git
186
187* 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.
188* 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).
189
190Updating the dictionaries
191-------------------------
192
193In the scenario where the user prefers not to follow the development version of codespell yet still opts to benefit from the frequently updated dictionary files, we recommend running a simple set of commands to achieve this ::
194
195 wget https://raw.githubusercontent.com/codespell-project/codespell/master/codespell_lib/data/dictionary.txt
196 codespell -D dictionary.txt
197
198The 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.
199
200You can also do the same thing for the other dictionaries listed here:
201 https://github.com/codespell-project/codespell/tree/master/codespell_lib/data
202
203License
204-------
205
206The Python script ``codespell`` with its library ``codespell_lib`` is available
207with the following terms:
208(*tl;dr*: `GPL v2`_)
209
210 Copyright (C) 2010-2011 Lucas De Marchi <lucas.de.marchi@gmail.com>
211
212 Copyright (C) 2011 ProFUSION embedded systems
213
214 This program is free software; you can redistribute it and/or modify
215 it under the terms of the GNU General Public License as published by
216 the Free Software Foundation; version 2 of the License.
217
218 This program is distributed in the hope that it will be useful,
219 but WITHOUT ANY WARRANTY; without even the implied warranty of
220 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
221 GNU General Public License for more details.
222
223 You should have received a copy of the GNU General Public License
224 along with this program; if not, see
225 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>.
226
227.. _GPL v2: http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
228
229``dictionary.txt`` and the other ``dictionary_*.txt`` files are a derived work of
230English Wikipedia and are released under the Creative Commons
231Attribution-Share-Alike License 3.0
232http://creativecommons.org/licenses/by-sa/3.0/
233