mirror of
https://github.com/cheat/cheat.git
synced 2024-10-31 21:21:02 +01:00
91f0d02de2
* feat: directory-scoped cheatpaths `cheat` now searches for a `.cheat` directory in the current working directory. If found, that directory is (temporarily) appended to the slice of cheatpaths. * makefile wip * fix: appeases linter Appeases linter (`go vet`) by adding quotation marks to YAML struct tags. * chore: modifies .gitignore Adds `tag` to `.gitignore` * feat: adds Makefile Adds a `Makefile` for managing build-related tasks. * chore: documents directory-local paths Adds documentation regarding the new directory-local cheatpath functionality. * chore: updates dependencies * chore: bumps version to 3.3.0 * chore: updates bin scripts - Removes `build_release.sh` - Places deprecation notice in `build_devel.sh`, as its purpose has been superceded by the `Makefile`.
204 lines
5.2 KiB
Markdown
204 lines
5.2 KiB
Markdown
cheat
|
|
=====
|
|
|
|
[](https://travis-ci.com/cheat/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.
|
|
|
|
|
|
|
|
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
|
|
----------
|
|
`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`:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```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:
|
|
|
|
```sh
|
|
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][cheatsheets].
|
|
|
|
|
|
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
|
|
# ...
|
|
```
|
|
|
|
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}'
|
|
```
|
|
|
|
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}'
|
|
```
|
|
|
|
|
|
Advanced Usage
|
|
--------------
|
|
`cheat` may be integrated with [fzf][]. See [fzf.bash][bash] for instructions.
|
|
(Support for other shells will be added in future releases.)
|
|
|
|
|
|
[Releases]: https://github.com/cheat/cheat/releases
|
|
[bash]: https://github.com/cheat/cheat/blob/master/scripts/fzf.bash
|
|
[cheatsheets]: https://github.com/cheat/cheatsheets
|
|
[fzf]: https://github.com/junegunn/fzf
|