Go to file
Chris Lane 0525b2331b chore: updates vendored dependencies
Updates `alecthomas/chroma` and `gopkg.in/yaml.v2` to newer versions.
2019-11-12 19:03:59 -05:00
.github/ISSUE_TEMPLATE chore: issue template labels 2019-11-04 18:43:52 -05:00
bin feat: updates build scripts 2019-11-12 19:02:42 -05:00
build Re-wrote from scratch in Golang 2019-10-20 10:02:28 -04:00
cmd/cheat fix: resolves #498 2019-11-07 20:24:08 -05:00
configs fixed some cli option typos 2019-11-05 15:53:21 +01:00
internal fix: repairs broken config unit-tests 2019-11-07 19:59:18 -05:00
mocks Re-wrote from scratch in Golang 2019-10-20 10:02:28 -04:00
scripts fix: file permissions 2019-11-05 18:49:05 -05:00
vendor chore: updates vendored dependencies 2019-11-12 19:03:59 -05:00
.gitignore Re-wrote from scratch in Golang 2019-10-20 10:02:28 -04:00
.travis.yml Add travis-ci 2019-10-27 18:31:16 -04:00
CONTRIBUTING.md chore: adds license and contributing file 2019-10-26 16:13:46 -04:00
go.mod Merge branch 'master' into dependabot/go_modules/github.com/alecthomas/chroma-0.6.9 2019-11-12 18:54:02 -05:00
go.sum chore: updates vendored dependencies 2019-11-12 19:03:59 -05:00
LICENSE.txt chore: adds license and contributing file 2019-10-26 16:13:46 -04:00
README.md fixed some cli option typos 2019-11-05 15:53:21 +01:00

cheat

Build Status

cheat allows you to create and view interactive cheatsheets on the command-line. It was designed to help remind *nix system administrators of options for commands that they use frequently, but not frequently enough to remember.

The obligatory xkcd

Use cheat with cheatsheets.

Example

The next time you're forced to disarm a nuclear weapon without consulting Google, you may run:

cheat tar

You will be presented with a cheatsheet resembling the following:

# To extract an uncompressed archive:
tar -xvf '/path/to/foo.tar'

# To extract a .gz archive:
tar -xzvf '/path/to/foo.tgz'

# To create a .gz archive:
tar -czvf '/path/to/foo.tgz' '/path/to/foo/'

# To extract a .bz2 archive:
tar -xjvf '/path/to/foo.tgz'

# To create a .bz2 archive:
tar -cjvf '/path/to/foo.tgz' '/path/to/foo/'

Installing

cheat has no dependencies. To install it, download the executable from the releases page and place it on your PATH.

Configuring

conf.yml

cheat is configured by a YAML file that can be generated with cheat --init:

mkdir -p ~/.config/cheat && cheat --init > ~/.config/cheat/conf.yml

By default, the config file is assumed to exist on an XDG-compliant configuration path like ~/.config/cheat/conf.yml. If you would like to store it elsewhere, you may export a CHEAT_CONFIG_PATH environment variable that specifies its path:

export CHEAT_CONFIG_PATH="~/.dotfiles/cheat/conf.yml"

Cheatsheets

Cheatsheets are plain-text files with no file extension, and are named according to the command used to view them:

cheat tar     # file is named "tar"
cheat foo/bar # file is named "bar", in a "foo" subdirectory

Cheatsheet text may optionally be preceeded by a YAML frontmatter header that assigns tags and specifies syntax:

---
syntax: javascript
tags: [ array, map ]
---
// To map over an array:
const squares = [1, 2, 3, 4].map(x => x * x);

The cheat executable includes no cheatsheets, but community-sourced cheatsheets are available.

Cheatpaths

Cheatsheets are stored on "cheatpaths", which are directories that contain cheetsheets. Cheatpaths are specified in the conf.yml file.

It can be useful to configure cheat against multiple cheatpaths. A common pattern is to store cheatsheets from multiple repositories on individual cheatpaths:

# conf.yml:
# ...
cheatpaths:
  - name: community                   # a name for the cheatpath
    path: ~/documents/cheat/community # the path's location on the filesystem
    tags: [ community ]               # these tags will be applied to all sheets on the path
    readonly: true                    # if true, `cheat` will not create new cheatsheets here

  - name: personal
    path: ~/documents/cheat/personal  # this is a separate directory and repository than above
    tags: [ personal ]
    readonly: false                   # new sheets may be written here
# ...

The readonly option instructs cheat not to edit (or create) any cheatsheets on the path. This is useful to prevent merge-conflicts from arising on upstream cheatsheet repositories.

If a user attempts to edit a cheatsheet on a read-only cheatpath, cheat will transparently copy that sheet to a writeable directory before opening it for editing.

Usage

To view a cheatsheet:

cheat tar      # a "top-level" cheatsheet
cheat foo/bar  # a "nested" cheatsheet

To edit a cheatsheet:

cheat -e tar     # opens the "tar" cheatsheet for editing, or creates it if it does not exist
cheat -e foo/bar # nested cheatsheets are accessed like this

To view the configured cheatpaths:

cheat -d

To list all available cheatsheets:

cheat -l

To list all cheatsheets that are tagged with "networking":

cheat -l -t networking

To list all cheatsheets on the "personal" path:

cheat -l -p personal

To search for the phrase "ssh" among cheatsheets:

cheat -s ssh

To search (by regex) for cheatsheets that contain an IP address:

cheat -r -s '(?:[0-9]{1,3}\.){3}[0-9]{1,3}'

Flags may be combined in intuitive ways. Example: to search sheets on the "personal" cheatpath that are tagged with "networking" and match a regex:

cheat -p personal -t networking --regex -s '(?:[0-9]{1,3}\.){3}[0-9]{1,3}'

Advanced Usage

cheat may be integrated with fzf. See fzf.bash for instructions. (Support for other shells will be added in future releases.)