diff --git a/INSTALLING.md b/INSTALLING.md new file mode 100644 index 0000000..1d44940 --- /dev/null +++ b/INSTALLING.md @@ -0,0 +1,77 @@ +Installing +========== +`cheat` has no runtime dependencies. As such, installing it is generally +straightforward. There are a few methods available: + +### Install manually +#### Unix-like +On Unix-like systems, you may simply paste the following snippet into your terminal: + +```sh +cd /tmp \ + && wget https://github.com/cheat/cheat/releases/download/4.2.5/cheat-linux-amd64.gz \ + && gunzip cheat-linux-amd64.gz \ + && chmod +x cheat-linux-amd64 \ + && sudo mv cheat-linux-amd64 /usr/local/bin/cheat +``` + +You may need to need to change the version number (`4.2.5`) and the archive +(`cheat-linux-amd64.gz`) depending on your platform. + +See the [releases page][releases] for a list of supported platforms. + +#### Windows +TODO: community support is requested here. Please open a PR if you'd like to +contribute installation instructions for Windows. + +### Install via `go install` +If you have `go` version `>=1.17` available on your `PATH`, you can install +`cheat` via `go install`: + +```sh +go install github.com/cheat/cheat/cmd/cheat@latest +``` + +### Install via package manager +Several community-maintained packages are also available: + +Package manager | Installing +---------------- | ----------- +[brew][] | `brew install cheat` +[docker][] | `alias cheat='docker run --rm bannmann/docker-cheat'` +[nix][] | `nix-env --install cheat` +[snap][] | `snap install cheat` + + + +## Configuring +Three things must be done before you can use `cheat`: +1. A config file must be generated +2. [`cheatpaths`][cheatpaths] must be configured +3. [Community cheatsheets][community] must be downloaded + +On first run, `cheat` will run an installer that will do all of the above +automatically. After the installer is complete, it is strongly advised that you +view the configuration file that was generated, as you may want to change some +of its default values (to enable colorization, change the paginator, etc). + +### conf.yml ### +`cheat` is configured by a YAML file that will be auto-generated on first run. + +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" +``` + +[brew]: https://formulae.brew.sh/formula/cheat +[cheatpaths]: README.md#cheatpaths +[community]: https://github.com/cheat/cheatsheets/ +[docker]: https://github.com/bannmann/docker-cheat +[nix]: https://pkgs.on-nix.com/nixpkgs/cheat/ +[pacman]: # +[releases]: https://github.com/cheat/cheat/releases +[snap]: https://snapcraft.io/cheat diff --git a/README.md b/README.md index 57b4c17..26af4d2 100644 --- a/README.md +++ b/README.md @@ -42,114 +42,6 @@ tar -xjvf '/path/to/foo.tgz' 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`. - -Alternatively, if you have [go][] installed, you may install `cheat` using `go -get`: - -```sh -go get -u github.com/cheat/cheat/cmd/cheat -``` - -Configuring ------------ -### conf.yml ### -`cheat` is configured by a YAML file that will be auto-generated on first run. - -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]. You will be asked if you would like to -install the community-sourced cheatsheets the first time you run `cheat`. - -### Script ### -You can manage the cheatsheets via a script `cheatsheets`. - -#### Download and install #### -```sh -mkdir -p ~/.local/bin -wget -O ~/.local/bin/cheatsheets https://raw.githubusercontent.com/cheat/cheat/master/scripts/git/cheatsheets -chmod +x ~/.local/bin/cheatsheets -``` - -#### Pull changes #### -To pull the community and personal cheatsheets call `cheatsheets pull` - -#### Push changes #### -To push your personal cheatsheets call `cheatsheets push` - -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` 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: @@ -210,7 +102,77 @@ cheat -p personal -t networking --regex -s '(?:[0-9]{1,3}\.){3}[0-9]{1,3}' ``` -Advanced Usage + +Installing +---------- +For installation and configuration instructions, see [INSTALLING.md][]. + +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]. 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` 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. + +Autocompletion -------------- Shell autocompletion is currently available for `bash`, `fish`, and `zsh`. Copy the relevant [completion script][completions] into the appropriate directory on @@ -223,8 +185,9 @@ Additionally, `cheat` supports enhanced autocompletion via integration with 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 -[go]: https://golang.org +[INSTALLING.md]: INSTALLING.md +[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 +[go]: https://golang.org