README
¶
woke
I stay woke - Erykah Badu
woke is a text file analysis tool that detects non-inclusive language in your source code.
Table of Contents
About
Creating an inclusive work environment is imperitive to a healthy, supportive, and productive culture, and an environment where everyone feels welcome and included.
woke's purpose is to point out places where improvements can be made by removing
non-inclusive language and replacing it with more inclusive alternatives.
Companies like GitHub, Twitter, and Apple are already pushing these changes.
Installation
Simple installation
curl -sSfL https://raw.githubusercontent.com/caitlinelfring/woke/main/install.sh | bash -s -- -b /usr/local/bin
Feel free to change the path from /usr/local/bin, just make sure woke
is available on your $PATH (check with woke --version).
Build from source
Install the go toolchain: https://golang.org/doc/install
go get -u github.com/caitlinelfring/woke
woke will be installed to $GOPATH/bin/woke.
Releases
Download the latest binary from Releases
Docker
You can run woke within docker. You will need to mount a volume that contains your source code and/or rules.
## Run with all defaults, within the mounted /src directory
docker run -v $(pwd):/src -w /src celfring/woke
## Provide rules config
docker run -v $(pwd):/src -w /src celfring/woke \
woke -c my-rules.yaml
Usage
$ woke --help
woke is a linter that will check your source code for usage of non-inclusive
language and provide suggestions for alternatives. Rules can be customized
to suit your needs.
Provide a list file globs for files you'd like to check.
Usage:
woke [globs ...] [flags]
Flags:
-c, --config string YAML file with list of rules
--debug Enable debug logging
--exit-1-on-failure Exit with exit code 1 on failures
-h, --help help for woke
-o, --output string Output type [text,simple] (default "text")
--stdin Read from stdin
-v, --version version for woke
File globs
By default, woke will run against all text files in your current directory.
To change this, supply a space-separated list of globs as the first argument.
This can be something like **/*.go, or a space-separated list of filenames.
$ woke test.txt
test.txt
4:2-4:11 warn Instead of 'whitelist', consider the following alternative(s): 'allowlist'
5:2-5:11 warn Instead of 'blacklist', consider the following alternative(s): 'denylist,blocklist'
stdin
You can also provide text to woke via stdin
$ echo "This has whitelist from stdin" | woke --stdin
/dev/stdin
1:8-1:17 warn Instead of 'whitelist', consider the following alternative(s): 'allowlist'
Rules
A set of default rules is provided in pkg/rule/default.go.
See example.yaml for an example of adding custom rules.
You can supply your own rules with -c path/to/rules.yaml
The syntax for rules is very basic. You just need a name, a list of terms to match that violate the rule, and a list of alternative suggestions.
rules:
- name: whitelist
terms:
- whitelist
- white-list
alternatives:
- allowlist
Ignoring files
In your config file, you can ignore files by adding:
ignore_files:
- .git/*
- other/files/in/repo
- globs/too/*
woke will also automatically ignore anything listed in .gitignore.
woke uses go-gitignore to ignores.
This follows the common .gitignore convention. See link for more details on matching.
.wokeignore
You may also specify a .wokeignore file at the root of the directory to add additional ignore files.
This also follows the .gitignore convention.
Exit Code
By default, woke will exit with a successful exit code when there are any rule failures.
The idea is, if you run woke on PRs, you may not want to block a merge, but you do
want to inform the author that they can make better word choices.
If you're using woke on PRs, you can choose to enforce these rules with a non-zero
exit code, but running woke --exit-1-on-failure.
Tools
TODO
- Benchmarking
- Tests
- What happens when run on a large repo?
- More rules
Resources
- https://buffer.com/resources/inclusive-language-tech/
- https://medium.com/pm101/inclusive-language-guide-for-tech-companies-and-startups-f5b254d4a5b7
- https://www.marketplace.org/2020/06/17/tech-companies-update-language-to-avoid-offensive-terms/
- https://tools.ietf.org/html/draft-knodel-terminology-02
License
This application is licensed under the MIT License, you may obtain a copy of it here.
Documentation
¶
Overview ¶
Copyright © 2020 Caitlin Elfring <celfring@gmail.com>
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Source Files
Directories