cheat/README.md
2013-08-15 18:55:59 -04:00

118 lines
3.5 KiB
Markdown

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](http://imgs.xkcd.com/comics/tar.png 'The obligatory xkcd')
`cheat` depends only on python.
Examples
--------
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:
```text
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/
```
To see what cheatsheets are availble, run `cheat` with no arguments.
Note that, while `cheat` was designed primarily for *nix system administrators,
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
----------
Do the following to install `cheat`:
1. Clone this repository and `cd` into it
2. Run `sudo ./install`
The `install` script will copy a python file into `/usr/local/bin/`, and will
also create a hidden `.cheat` folder (containing the cheatsheet content) in
your home directory.
Modifying Cheatsheets
---------------------
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.
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
in the `~/.cheat/tar` file. To add a cheatsheet for a `foo` command, you would
create file `~/.cheat/foo`, whereby that file contained the cheatsheet content.
Note that `cheat` supports "subcommands" simply by naming files appropriately.
Thus, if you wanted to create a cheatsheet not only (for example) for `git` but
also for `git commit`, you could do so be creating cheatsheet files of the
appropriate names (`git` and `git commit`).
After you've customized your cheatsheets, I urge you to track `~/.cheat/` along
with your [dotfiles][].
Setting a CHEATPATH
----------------------
By default, all cheatsheets are installed to `~/.cheat/`, but you can instruct
`cheat` to look for cheatsheets in other directories by exporting a `CHEATPATH`
environment variable:
```bash
export CHEATPATH=/path/to/my/cheats
```
You may, of course, append multiple directories to your `CHEATPATH`:
```bash
export CHEATPATH=$CHEATPATH:/path/to/more/cheats
```
Contributing
------------
If you would like to contribute cheetsheets or program functionality, please
fork this repository, make your chanages, and send me a pull request.
Related Projects
----------------
- [lucaswerkmeister/cheats][1]: An implementation of this concept in pure bash
that also allows not only for numerical indexing of subcomands but also
supports running commands interactively.
- [jahendrie/cheat][2]: A bash-only implmentation that additionally allows for
cheatsheets to be created and `grep` searched from the command-line.
([jahendrie][] contributed key ideas to this project as well.)
[dotfiles]: http://dotfiles.github.io/
[jahendrie]: https://github.com/jahendrie
[1]: https://github.com/lucaswerkmeister/cheats
[2]: https://github.com/jahendrie/cheat