mirror of
https://github.com/cheat/cheat.git
synced 2024-12-22 04:35:06 +01:00
docs: create INSTALLING.md
- Create `INSTALLING.md` - Update the `README.md`
This commit is contained in:
Christopher Allen Lane
parent
1cb53697d2
commit
65f6be3fd8
77
INSTALLING.md
Normal file
77
INSTALLING.md
Normal file
@ -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/'
|
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
|
Usage
|
||||||
-----
|
-----
|
||||||
To view a cheatsheet:
|
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
|
Shell autocompletion is currently available for `bash`, `fish`, and `zsh`. Copy
|
||||||
the relevant [completion script][completions] into the appropriate directory on
|
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`
|
1. Ensure that `fzf` is available on your `$PATH`
|
||||||
2. Set an envvar: `export CHEAT_USE_FZF=true`
|
2. Set an envvar: `export CHEAT_USE_FZF=true`
|
||||||
|
|
||||||
[Releases]: https://github.com/cheat/cheat/releases
|
[INSTALLING.md]: INSTALLING.md
|
||||||
[cheatsheets]: https://github.com/cheat/cheatsheets
|
[Releases]: https://github.com/cheat/cheat/releases
|
||||||
[completions]: https://github.com/cheat/cheat/tree/master/scripts
|
[cheatsheets]: https://github.com/cheat/cheatsheets
|
||||||
[fzf]: https://github.com/junegunn/fzf
|
[completions]: https://github.com/cheat/cheat/tree/master/scripts
|
||||||
[go]: https://golang.org
|
[fzf]: https://github.com/junegunn/fzf
|
||||||
|
[go]: https://golang.org
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user