cheat/README.md

170 lines
4.3 KiB
Markdown
Raw Normal View History

[![PyPI](https://img.shields.io/pypi/v/cheat.svg)](https://pypi.python.org/pypi/cheat/)
2013-08-11 01:08:21 +02:00
cheat
2013-07-31 04:48:07 +02:00
=====
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')
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:
```sh
# 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
```
To see what cheatsheets are available, run `cheat -l`.
2013-08-11 00:56:50 +02:00
Note that, while `cheat` was designed primarily for \*nix system administrators,
2013-08-11 00:56:50 +02:00
it is agnostic as to what content it stores. If you would like to use `cheat`
to store notes on your favorite cookie recipes, feel free.
Installing
2014-04-27 16:47:04 +02:00
----------
It is recommended to install `cheat` with `pip`:
```sh
[sudo] pip install cheat
```
2013-08-11 00:56:50 +02:00
[Other installation methods are available][installing].
2013-08-11 00:56:50 +02:00
Modifying Cheatsheets
2014-04-27 16:47:04 +02:00
---------------------
2013-08-11 00:56:50 +02:00
The value of `cheat` is that it allows you to create your own cheatsheets - the
defaults are meant to serve only as a starting point, and can and should be
modified.
2013-08-11 21:57:11 +02:00
Cheatsheets are stored in the `~/.cheat/` directory, and are named on a
per-keyphrase basis. In other words, the content for the `tar` cheatsheet lives
2014-04-27 16:47:04 +02:00
in the `~/.cheat/tar` file.
Provided that you have a `CHEAT_EDITOR`, `VISUAL`, or `EDITOR` environment
variable set, you may edit cheatsheets with:
2014-04-27 16:47:04 +02:00
```sh
cheat -e foo
```
2013-08-11 00:56:50 +02:00
If the `foo` cheatsheet already exists, it will be opened for editing.
2014-04-27 16:47:04 +02:00
Otherwise, it will be created automatically.
2013-08-11 00:56:50 +02:00
2013-08-11 21:57:11 +02:00
After you've customized your cheatsheets, I urge you to track `~/.cheat/` along
2013-08-11 00:56:50 +02:00
with your [dotfiles][].
2014-04-27 16:47:04 +02:00
Configuring
-----------
### Setting a CHEAT_USER_DIR ###
2013-09-01 19:56:49 +02:00
Personal cheatsheets are saved in the `~/.cheat` directory by default, but you
can specify a different default by exporting a `CHEAT_USER_DIR` environment
2013-09-01 19:56:49 +02:00
variable:
```sh
export CHEAT_USER_DIR='/path/to/my/cheats'
```
### Setting a CHEAT_PATH ###
2013-09-01 19:56:49 +02:00
You can additionally instruct `cheat` to look for cheatsheets in other
directories by exporting a `CHEAT_PATH` environment variable:
```sh
export CHEAT_PATH='/path/to/my/cheats'
```
You may, of course, append multiple directories to your `CHEAT_PATH`:
```sh
export CHEAT_PATH="$CHEAT_PATH:/path/to/more/cheats"
```
You may view which directories are on your `CHEAT_PATH` with `cheat -d`.
2014-04-27 16:47:04 +02:00
### Enabling Syntax Highlighting ###
`cheat` can optionally apply syntax highlighting to your cheatsheets. To
enable syntax highlighting, export a `CHEAT_COLORS` environment variable:
```sh
export CHEAT_COLORS=true
```
Note that [pygments][] must be installed on your system for this to work.
#### Specifying a Syntax Highlighter ####
You may manually specify which syntax highlighter to use for each cheatsheet by
wrapping the sheet's contents in a [Github-Flavored Markdown code-fence][gfm].
Example:
<pre>
```sql
-- to select a user by ID
SELECT *
FROM Users
WHERE id = 100
```
</pre>
If no syntax highlighter is specified, the `bash` highlighter will be used by
default.
### Enabling Search Match Highlighting ###
`cheat` can optionally be configured to highlight search term matches in search
results. To do so, export a `CHEAT_HIGHLIGHT` environment variable with a value
of one of the following:
- blue
- cyan
- green
- grey
- magenta
- red
- white
- yellow
Note that the `termcolor` module must be installed on your system for this to
work.
See Also:
---------
- [Enabling Command-line Autocompletion][autocompletion]
- [Related Projects][related-projects]
[autocompletion]: https://github.com/cheat/cheat/wiki/Enabling-Command-line-Autocompletion
[dotfiles]: http://dotfiles.github.io/
[gfm]: https://help.github.com/articles/creating-and-highlighting-code-blocks/
[installing]: https://github.com/cheat/cheat/wiki/Installing
[pygments]: http://pygments.org/
[related-projects]: https://github.com/cheat/cheat/wiki/Related-Projects