cheat/README.md

214 lines
5.7 KiB
Markdown
Raw Permalink Normal View History

2013-08-11 01:08:21 +02:00
cheat
2013-07-31 04:48:07 +02:00
=====
2019-10-27 23:44:44 +01:00
[![Build Status](https://travis-ci.com/cheat/cheat.svg?branch=master)](https://travis-ci.com/cheat/cheat)
2013-08-11 00:56:50 +02:00
`cheat` allows you to create and view interactive cheatsheets on the
2013-08-11 21:57:11 +02:00
command-line. It was designed to help remind \*nix system administrators of
2013-08-11 00:56:50 +02:00
options for commands that they use frequently, but not frequently enough to
remember.
![The obligatory xkcd](http://imgs.xkcd.com/comics/tar.png 'The obligatory xkcd')
Use `cheat` with [cheatsheets][].
2013-08-11 21:57:11 +02:00
2014-04-27 16:47:04 +02:00
Example
-------
2013-08-11 00:56:50 +02:00
The next time you're forced to disarm a nuclear weapon without consulting
Google, you may run:
```sh
cheat tar
```
2013-08-11 00:56:50 +02:00
You will be presented with a cheatsheet resembling the following:
2013-08-11 00:56:50 +02:00
```sh
2019-10-27 23:44:44 +01:00
# To extract an uncompressed archive:
tar -xvf '/path/to/foo.tar'
2013-08-11 00:56:50 +02:00
# To extract a .gz archive:
tar -xzvf '/path/to/foo.tgz'
2013-08-11 00:56:50 +02:00
# To create a .gz archive:
tar -czvf '/path/to/foo.tgz' '/path/to/foo/'
2013-08-11 00:56:50 +02:00
# To extract a .bz2 archive:
tar -xjvf '/path/to/foo.tgz'
2013-08-11 00:56:50 +02:00
# To create a .bz2 archive:
tar -cjvf '/path/to/foo.tgz' '/path/to/foo/'
2013-08-11 00:56:50 +02:00
```
Installing
2014-04-27 16:47:04 +02:00
----------
`cheat` has no dependencies. To install it, download the executable from the
[releases][] page and place it on your `PATH`.
Configuring
-----------
### conf.yml ###
feat(installer): implement "installer" Squashed commit of the following: commit 5c322e79b7b6fa6bef51cac2f9b03fe2eaf08163 Author: Chris Lane <chris@chris-allen-lane.com> Date: Fri Mar 6 19:56:56 2020 -0500 docs(README): update the `README` Update the `README` to document the improved config-generation mechanism. commit 803e1f014cc89c30bfb80549b64195235b8b9f62 Author: Chris Lane <chris@chris-allen-lane.com> Date: Fri Mar 6 19:19:49 2020 -0500 feat(config-init): platform-specific pathing Update `--init` subcommand to rely upon the same platform-detection intelligence that was previously implemented by the "installer". The installer and `--init` should now produce identical config files. commit 99c48097e2e23755710d08a099918675895192f7 Author: Chris Lane <chris@chris-allen-lane.com> Date: Fri Mar 6 18:26:33 2020 -0500 feat(installer): platform-correct config templating Modify the "installer" to populate cheatpaths with sensible defaults based on the detection of the user's operating system and environment. commit 8e1580ff5a30ae3241c3f02b806666583c5d44b2 Author: Chris Lane <chris@chris-allen-lane.com> Date: Thu Mar 5 20:19:58 2020 -0500 fix(tests): fix `config.Paths` tests Refactor `config.Paths` (by externalizing a call to `homedir.Dir`) to decouple it from filesystem paths, thus facilitating cleaner unit-tests. commit a08dca70d90bb6d568d44abf76b2bd911d929001 Author: Chris Lane <chris@chris-allen-lane.com> Date: Thu Mar 5 18:14:27 2020 -0500 feat(installer): default path selection Modify the installer to improve default config and cheatsheet path selection. commit e15bc6c966bfdca3b507504c95a34b74e264be11 Author: Chris Lane <chris@chris-allen-lane.com> Date: Thu Mar 5 17:49:50 2020 -0500 fix(typo): correct comment typo in `main.go` commit efd09575df4422449d6178cd922a680e0f871c21 Author: Chris Lane <chris@chris-allen-lane.com> Date: Thu Mar 5 17:46:49 2020 -0500 feat(config): refactor config path detection Previously, failing other checks, on Unix and BSD systems, `config.Paths` would attempt to compute the user's home directory by reading the `HOME` environment variable. This change deprecates that approach with a call to `homedir.Dir`, which is used elsewhere throughout the application. commit ec10244ebeb2a48e5c694aeabb8bcbc177a77369 Author: Chris Lane <chris@chris-allen-lane.com> Date: Thu Mar 5 17:15:28 2020 -0500 chore(installer): delete unused file Delete `installer/installer.go`, which (in hindsight) was unnecessary. commit ebd9ec62873d7f286586ea0af9113d74b8a1d2f2 Author: Chris Lane <chris@chris-allen-lane.com> Date: Wed Mar 4 19:31:13 2020 -0500 wip(installer): stub experimental "installer" Stubs out an experimental "installer" that will help new users to quickly configure `cheat`. commit ecac5a09717a4a4714637946d3699da5db97fcc7 Author: Chris Lane <chris@chris-allen-lane.com> Date: Wed Mar 4 19:30:12 2020 -0500 chore(dependencies): updates vendored dependencies
2020-03-07 02:17:26 +01:00
`cheat` is configured by a YAML file that will be auto-generated on first run.
Should you need to create a config file manually, you can do
so via:
```sh
mkdir -p ~/.config/cheat && cheat --init > ~/.config/cheat/conf.yml
```
2013-08-11 00:56:50 +02:00
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:
```sh
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:
2013-08-11 00:56:50 +02:00
```sh
cheat tar # file is named "tar"
cheat foo/bar # file is named "bar", in a "foo" subdirectory
```
2014-04-27 16:47:04 +02:00
Cheatsheet text may optionally be preceeded by a YAML frontmatter header that
assigns tags and specifies syntax:
2014-04-27 16:47:04 +02:00
```
---
syntax: javascript
tags: [ array, map ]
---
// To map over an array:
const squares = [1, 2, 3, 4].map(x => x * x);
```
2013-08-11 00:56:50 +02:00
The `cheat` executable includes no cheatsheets, but [community-sourced
feat(installer): implement "installer" Squashed commit of the following: commit 5c322e79b7b6fa6bef51cac2f9b03fe2eaf08163 Author: Chris Lane <chris@chris-allen-lane.com> Date: Fri Mar 6 19:56:56 2020 -0500 docs(README): update the `README` Update the `README` to document the improved config-generation mechanism. commit 803e1f014cc89c30bfb80549b64195235b8b9f62 Author: Chris Lane <chris@chris-allen-lane.com> Date: Fri Mar 6 19:19:49 2020 -0500 feat(config-init): platform-specific pathing Update `--init` subcommand to rely upon the same platform-detection intelligence that was previously implemented by the "installer". The installer and `--init` should now produce identical config files. commit 99c48097e2e23755710d08a099918675895192f7 Author: Chris Lane <chris@chris-allen-lane.com> Date: Fri Mar 6 18:26:33 2020 -0500 feat(installer): platform-correct config templating Modify the "installer" to populate cheatpaths with sensible defaults based on the detection of the user's operating system and environment. commit 8e1580ff5a30ae3241c3f02b806666583c5d44b2 Author: Chris Lane <chris@chris-allen-lane.com> Date: Thu Mar 5 20:19:58 2020 -0500 fix(tests): fix `config.Paths` tests Refactor `config.Paths` (by externalizing a call to `homedir.Dir`) to decouple it from filesystem paths, thus facilitating cleaner unit-tests. commit a08dca70d90bb6d568d44abf76b2bd911d929001 Author: Chris Lane <chris@chris-allen-lane.com> Date: Thu Mar 5 18:14:27 2020 -0500 feat(installer): default path selection Modify the installer to improve default config and cheatsheet path selection. commit e15bc6c966bfdca3b507504c95a34b74e264be11 Author: Chris Lane <chris@chris-allen-lane.com> Date: Thu Mar 5 17:49:50 2020 -0500 fix(typo): correct comment typo in `main.go` commit efd09575df4422449d6178cd922a680e0f871c21 Author: Chris Lane <chris@chris-allen-lane.com> Date: Thu Mar 5 17:46:49 2020 -0500 feat(config): refactor config path detection Previously, failing other checks, on Unix and BSD systems, `config.Paths` would attempt to compute the user's home directory by reading the `HOME` environment variable. This change deprecates that approach with a call to `homedir.Dir`, which is used elsewhere throughout the application. commit ec10244ebeb2a48e5c694aeabb8bcbc177a77369 Author: Chris Lane <chris@chris-allen-lane.com> Date: Thu Mar 5 17:15:28 2020 -0500 chore(installer): delete unused file Delete `installer/installer.go`, which (in hindsight) was unnecessary. commit ebd9ec62873d7f286586ea0af9113d74b8a1d2f2 Author: Chris Lane <chris@chris-allen-lane.com> Date: Wed Mar 4 19:31:13 2020 -0500 wip(installer): stub experimental "installer" Stubs out an experimental "installer" that will help new users to quickly configure `cheat`. commit ecac5a09717a4a4714637946d3699da5db97fcc7 Author: Chris Lane <chris@chris-allen-lane.com> Date: Wed Mar 4 19:30:12 2020 -0500 chore(dependencies): updates vendored dependencies
2020-03-07 02:17:26 +01:00
cheatsheets are available][cheatsheets]. You will be asked if you would like to
install the community-sourced cheatsheets the first time you run `cheat`.
2013-08-11 00:56:50 +02:00
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:
```yaml
# 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
# ...
```
2013-08-11 00:56:50 +02:00
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.
### Directory-scoped Cheatpaths ###
At times, it can be useful to closely associate cheatsheets with a directory on
your filesystem. `cheat` facilitates this by searching for a `.cheat` folder in
the current working directory. If found, the `.cheat` directory will
(temporarily) be added to the cheatpaths.
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 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}'
```
2019-11-05 15:53:21 +01:00
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
2019-11-05 15:53:21 +01:00
cheat -p personal -t networking --regex -s '(?:[0-9]{1,3}\.){3}[0-9]{1,3}'
```
Advanced Usage
--------------
Shell autocompletion is currently available for `bash`, `fish`, and `zsh`. Copy
the relevant [completion script][completions] into the appropriate directory on
your filesystem to enable autocompletion. (This directory will vary depending
on operating system and shell specifics.)
Additionally, `cheat` supports enhanced autocompletion via integration with
[fzf][]. To enable `fzf` integration:
1. Ensure that `fzf` is available on your `$PATH`
2. Set an envvar: `export CHEAT_USE_FZF=true`
[Releases]: https://github.com/cheat/cheat/releases
[cheatsheets]: https://github.com/cheat/cheatsheets
[completions]: https://github.com/cheat/cheat/tree/master/scripts
[fzf]: https://github.com/junegunn/fzf