1[![Build Status](https://travis-ci.org/client9/misspell.svg?branch=master)](https://travis-ci.org/client9/misspell) [![Go Report Card](https://goreportcard.com/badge/github.com/client9/misspell)](https://goreportcard.com/report/github.com/client9/misspell) [![GoDoc](https://godoc.org/github.com/client9/misspell?status.svg)](https://godoc.org/github.com/client9/misspell) [![Coverage](http://gocover.io/_badge/github.com/client9/misspell)](http://gocover.io/github.com/client9/misspell) [![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://raw.githubusercontent.com/client9/misspell/master/LICENSE) 2 3Correct commonly misspelled English words... quickly. 4 5### Install 6 7 8If you just want a binary and to start using `misspell`: 9 10``` 11curl -L -o ./install-misspell.sh https://git.io/misspell 12sh ./install-misspell.sh 13``` 14 15 16Both will install as `./bin/misspell`. You can adjust the download location using the `-b` flag. File a ticket if you want another platform supported. 17 18 19If you use [Go](https://golang.org/), the best way to run `misspell` is by using [gometalinter](#gometalinter). Otherwise, install `misspell` the old-fashioned way: 20 21``` 22go get -u github.com/client9/misspell/cmd/misspell 23``` 24 25and misspell will be in your `GOPATH` 26 27 28Also if you like to live dangerously, one could do 29 30```bash 31curl -L https://git.io/misspell | bash 32``` 33 34### Usage 35 36 37```bash 38$ misspell all.html your.txt important.md files.go 39your.txt:42:10 found "langauge" a misspelling of "language" 40 41# ^ file, line, column 42``` 43 44``` 45$ misspell -help 46Usage of misspell: 47 -debug 48 Debug matching, very slow 49 -error 50 Exit with 2 if misspelling found 51 -f string 52 'csv', 'sqlite3' or custom Golang template for output 53 -i string 54 ignore the following corrections, comma separated 55 -j int 56 Number of workers, 0 = number of CPUs 57 -legal 58 Show legal information and exit 59 -locale string 60 Correct spellings using locale perferances for US or UK. Default is to use a neutral variety of English. Setting locale to US will correct the British spelling of 'colour' to 'color' 61 -o string 62 output file or [stderr|stdout|] (default "stdout") 63 -q Do not emit misspelling output 64 -source string 65 Source mode: auto=guess, go=golang source, text=plain or markdown-like text (default "auto") 66 -w Overwrite file with corrections (default is just to display) 67``` 68 69## FAQ 70 71* [Automatic Corrections](#correct) 72* [Converting UK spellings to US](#locale) 73* [Using pipes and stdin](#stdin) 74* [Golang special support](#golang) 75* [gometalinter support](#gometalinter) 76* [CSV Output](#csv) 77* [Using SQLite3](#sqlite) 78* [Changing output format](#output) 79* [Checking a folder recursively](#recursive) 80* [Performance](#performance) 81* [Known Issues](#issues) 82* [Debugging](#debug) 83* [False Negatives and missing words](#missing) 84* [Origin of Word Lists](#words) 85* [Software License](#license) 86* [Problem statement](#problem) 87* [Other spelling correctors](#others) 88* [Other ideas](#otherideas) 89 90<a name="correct"></a> 91### How can I make the corrections automatically? 92 93Just add the `-w` flag! 94 95``` 96$ misspell -w all.html your.txt important.md files.go 97your.txt:9:21:corrected "langauge" to "language" 98 99# ^ File is rewritten only if a misspelling is found 100``` 101 102<a name="locale"></a> 103### How do I convert British spellings to American (or vice-versa)? 104 105Add the `-locale US` flag! 106 107```bash 108$ misspell -locale US important.txt 109important.txt:10:20 found "colour" a misspelling of "color" 110``` 111 112Add the `-locale UK` flag! 113 114```bash 115$ echo "My favorite color is blue" | misspell -locale UK 116stdin:1:3:found "favorite color" a misspelling of "favourite colour" 117``` 118 119Help is appreciated as I'm neither British nor an 120expert in the English language. 121 122<a name="recursive"></a> 123### How do you check an entire folder recursively? 124 125Just list a directory you'd like to check 126 127```bash 128misspell . 129misspell aDirectory anotherDirectory aFile 130``` 131 132You can also run misspell recursively using the following shell tricks: 133 134```bash 135misspell directory/**/* 136``` 137 138or 139 140```bash 141find . -type f | xargs misspell 142``` 143 144You can select a type of file as well. The following examples selects all `.txt` files that are *not* in the `vendor` directory: 145 146```bash 147find . -type f -name '*.txt' | grep -v vendor/ | xargs misspell -error 148``` 149 150<a name="stdin"></a> 151### Can I use pipes or `stdin` for input? 152 153Yes! 154 155Print messages to `stderr` only: 156 157```bash 158$ echo "zeebra" | misspell 159stdin:1:0:found "zeebra" a misspelling of "zebra" 160``` 161 162Print messages to `stderr`, and corrected text to `stdout`: 163 164```bash 165$ echo "zeebra" | misspell -w 166stdin:1:0:corrected "zeebra" to "zebra" 167zebra 168``` 169 170Only print the corrected text to `stdout`: 171 172```bash 173$ echo "zeebra" | misspell -w -q 174zebra 175``` 176 177<a name="golang"></a> 178### Are there special rules for golang source files? 179 180Yes! If the file ends in `.go`, then misspell will only check spelling in 181comments. 182 183If you want to force a file to be checked as a golang source, use `-source=go` 184on the command line. Conversely, you can check a golang source as if it were 185pure text by using `-source=text`. You might want to do this since many 186variable names have misspellings in them! 187 188### Can I check only-comments in other other programming languages? 189 190I'm told the using `-source=go` works well for ruby, javascript, java, c and 191c++. 192 193It doesn't work well for python and bash. 194 195<a name="gometalinter"></a> 196### Does this work with gometalinter? 197 198[gometalinter](https://github.com/alecthomas/gometalinter) runs 199multiple golang linters. Starting on [2016-06-12](https://github.com/alecthomas/gometalinter/pull/134) 200gometalinter supports `misspell` natively but it is disabled by default. 201 202```bash 203# update your copy of gometalinter 204go get -u github.com/alecthomas/gometalinter 205 206# install updates and misspell 207gometalinter --install --update 208``` 209 210To use, just enable `misspell` 211 212``` 213gometalinter --enable misspell ./... 214``` 215 216Note that gometalinter only checks golang files, and uses the default options 217of `misspell` 218 219You may wish to run this on your plaintext (.txt) and/or markdown files too. 220 221 222<a name="csv"></a> 223### How Can I Get CSV Output? 224 225Using `-f csv`, the output is standard comma-seprated values with headers in the first row. 226 227``` 228misspell -f csv * 229file,line,column,typo,corrected 230"README.md",9,22,langauge,language 231"README.md",47,25,langauge,language 232``` 233 234<a name="sqlite"></a> 235### How can I export to SQLite3? 236 237Using `-f sqlite`, the output is a [sqlite3](https://www.sqlite.org/index.html) dump-file. 238 239```bash 240$ misspell -f sqlite * > /tmp/misspell.sql 241$ cat /tmp/misspell.sql 242 243PRAGMA foreign_keys=OFF; 244BEGIN TRANSACTION; 245CREATE TABLE misspell( 246 "file" TEXT, 247 "line" INTEGER,i 248 "column" INTEGER,i 249 "typo" TEXT, 250 "corrected" TEXT 251); 252INSERT INTO misspell VALUES("install.txt",202,31,"immediatly","immediately"); 253# etc... 254COMMIT; 255``` 256 257```bash 258$ sqlite3 -init /tmp/misspell.sql :memory: 'select count(*) from misspell' 2591 260``` 261 262With some tricks you can directly pipe output to sqlite3 by using `-init /dev/stdin`: 263 264``` 265misspell -f sqlite * | sqlite3 -init /dev/stdin -column -cmd '.width 60 15' ':memory' \ 266 'select substr(file,35),typo,count(*) as count from misspell group by file, typo order by count desc;' 267``` 268 269<a name="ignore"></a> 270### How can I ignore rules? 271 272Using the `-i "comma,separated,rules"` flag you can specify corrections to ignore. 273 274For example, if you were to run `misspell -w -error -source=text` against document that contains the string `Guy Finkelshteyn Braswell`, misspell would change the text to `Guy Finkelstheyn Bras well`. You can then 275determine the rules to ignore by reverting the change and running the with the `-debug` flag. You can then see 276that the corrections were `htey -> they` and `aswell -> as well`. To ignore these two rules, you add `-i "htey,aswell"` to 277your command. With debug mode on, you can see it print the corrections, but it will no longer make them. 278 279<a name="output"></a> 280### How can I change the output format? 281 282Using the `-f template` flag you can pass in a 283[golang text template](https://golang.org/pkg/text/template/) to format the output. 284 285One can use `printf "%q" VALUE` to safely quote a value. 286 287The default template is compatible with [gometalinter](https://github.com/alecthomas/gometalinter) 288``` 289{{ .Filename }}:{{ .Line }}:{{ .Column }}:corrected {{ printf "%q" .Original }} to "{{ printf "%q" .Corrected }}" 290``` 291 292To just print probable misspellings: 293 294``` 295-f '{{ .Original }}' 296``` 297 298<a name="problem"></a> 299### What problem does this solve? 300 301This corrects commonly misspelled English words in computer source 302code, and other text-based formats (`.txt`, `.md`, etc). 303 304It is designed to run quickly so it can be 305used as a [pre-commit hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) 306with minimal burden on the developer. 307 308It does not work with binary formats (e.g. Word, etc). 309 310It is not a complete spell-checking program nor a grammar checker. 311 312<a name="others"></a> 313### What are other misspelling correctors and what's wrong with them? 314 315Some other misspelling correctors: 316 317* https://github.com/vlajos/misspell_fixer 318* https://github.com/lyda/misspell-check 319* https://github.com/lucasdemarchi/codespell 320 321They all work but had problems that prevented me from using them at scale: 322 323* slow, all of the above check one misspelling at a time (i.e. linear) using regexps 324* not MIT/Apache2 licensed (or equivalent) 325* have dependencies that don't work for me (python3, bash, linux sed, etc) 326* don't understand American vs. British English and sometimes makes unwelcome "corrections" 327 328That said, they might be perfect for you and many have more features 329than this project! 330 331<a name="performance"></a> 332### How fast is it? 333 334Misspell is easily 100x to 1000x faster than other spelling correctors. You 335should be able to check and correct 1000 files in under 250ms. 336 337This uses the mighty power of golang's 338[strings.Replacer](https://golang.org/pkg/strings/#Replacer) which is 339a implementation or variation of the 340[Aho–Corasick algorithm](https://en.wikipedia.org/wiki/Aho–Corasick_algorithm). 341This makes multiple substring matches *simultaneously*. 342 343In addition this uses multiple CPU cores to work on multiple files. 344 345<a name="issues"></a> 346### What problems does it have? 347 348Unlike the other projects, this doesn't know what a "word" is. There may be 349more false positives and false negatives due to this. On the other hand, it 350sometimes catches things others don't. 351 352Either way, please file bugs and we'll fix them! 353 354Since it operates in parallel to make corrections, it can be non-obvious to 355determine exactly what word was corrected. 356 357<a name="debug"></a> 358### It's making mistakes. How can I debug? 359 360Run using `-debug` flag on the file you want. It should then print what word 361it is trying to correct. Then [file a 362bug](https://github.com/client9/misspell/issues) describing the problem. 363Thanks! 364 365<a name="missing"></a> 366### Why is it making mistakes or missing items in golang files? 367 368The matching function is *case-sensitive*, so variable names that are multiple 369worlds either in all-upper or all-lower case sometimes can cause false 370positives. For instance a variable named `bodyreader` could trigger a false 371positive since `yrea` is in the middle that could be corrected to `year`. 372Other problems happen if the variable name uses a English contraction that 373should use an apostrophe. The best way of fixing this is to use the 374[Effective Go naming 375conventions](https://golang.org/doc/effective_go.html#mixed-caps) and use 376[camelCase](https://en.wikipedia.org/wiki/CamelCase) for variable names. You 377can check your code using [golint](https://github.com/golang/lint) 378 379<a name="license"></a> 380### What license is this? 381 382The main code is [MIT](https://github.com/client9/misspell/blob/master/LICENSE). 383 384Misspell also makes uses of the Golang standard library and contains a modified version of Golang's [strings.Replacer](https://golang.org/pkg/strings/#Replacer) 385which are covered under a [BSD License](https://github.com/golang/go/blob/master/LICENSE). Type `misspell -legal` for more details or see [legal.go](https://github.com/client9/misspell/blob/master/legal.go) 386 387<a name="words"></a> 388### Where do the word lists come from? 389 390It started with a word list from 391[Wikipedia](https://en.wikipedia.org/wiki/Wikipedia:Lists_of_common_misspellings/For_machines). 392Unfortunately, this list had to be highly edited as many of the words are 393obsolete or based from mistakes on mechanical typewriters (I'm guessing). 394 395Additional words were added based on actually mistakes seen in 396the wild (meaning self-generated). 397 398Variations of UK and US spellings are based on many sources including: 399 400* http://www.tysto.com/uk-us-spelling-list.html (with heavy editing, many are incorrect) 401* http://www.oxforddictionaries.com/us/words/american-and-british-spelling-american (excellent site but incomplete) 402* Diffing US and UK [scowl dictionaries](http://wordlist.aspell.net) 403 404American English is more accepting of spelling variations than is British 405English, so "what is American or not" is subject to opinion. Corrections and help welcome. 406 407<a name="otherideas"></a> 408### What are some other enhancements that could be done? 409 410Here's some ideas for enhancements: 411 412*Capitalization of proper nouns* could be done (e.g. weekday and month names, country names, language names) 413 414*Opinionated US spellings* US English has a number of words with alternate 415spellings. Think [adviser vs. 416advisor](http://grammarist.com/spelling/adviser-advisor/). While "advisor" is not wrong, the opinionated US 417locale would correct "advisor" to "adviser". 418 419*Versioning* Some type of versioning is needed so reporting mistakes and errors is easier. 420 421*Feedback* Mistakes would be sent to some server for agregation and feedback review. 422 423*Contractions and Apostrophes* This would optionally correct "isnt" to 424"isn't", etc. 425