README

!Workflow status

 cheat

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:

sh
cheat tar


You will be presented with a cheatsheet resembling the following:

sh
 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
For installation and configuration instructions, see [INSTALLING.md][].

 Usage
To view a cheatsheet:

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


To edit a cheatsheet:

sh
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:

sh
cheat -d


To list all available cheatsheets:

sh
cheat -l


To briefly list all cheatsheets (names and tags only):

sh
cheat -b


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

sh
cheat -l -t networking


To list all cheatsheets on the "personal" path:

sh
cheat -l -p personal


To search for the phrase "ssh" among cheatsheets:

sh
cheat -s ssh


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

sh
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:

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


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

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


Cheatsheet text may optionally be preceded 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);


Syntax highlighting is provided by [Chroma][], and the syntax value may be
set to any lexer name that Chroma supports. See Chroma's [supported
languages][] for a complete list.

The cheat executable includes no cheatsheets, but [community-sourced
cheatsheets are available][cheatsheets]. You will be asked if you would like to
install the community-sourced cheatsheets the first time you run cheat.

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

It can be useful to configure cheat a