mirror of https://github.com/cheat/cheat.git
docs: create `INSTALLING.md`
- Create `INSTALLING.md` - Update the `README.md`
This commit is contained in:
Christopher Allen Lane
parent
1cb53697d2
commit
65f6be3fd8
|
|
@ -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`
|
||||
|
||||
<!--[pacman][] |-->
|
||||
|
||||
## 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
|
||||
191
README.md
191
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue