From ecfb83a3b005b7d7d2bc6f0449cbe766d04f2558 Mon Sep 17 00:00:00 2001 From: Christopher Allen Lane Date: Sun, 15 Feb 2026 12:56:58 -0500 Subject: [PATCH] docs: clean up project documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Convert all headings from underline style to ATX style - Fix heading hierarchy in INSTALLING.md (H3→H2, H4→H3) - Move Installing section before Usage in README - Bump install snippet version from 4.5.1 to 4.7.0 - Add feature request guidance to CONTRIBUTING.md - Add installer package and .cheat discovery to CLAUDE.md - Remove unused reference links and dead HTML comments - Trim trailing whitespace Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 7 ++++++- CONTRIBUTING.md | 7 +++++-- INSTALLING.md | 25 +++++++++++-------------- README.md | 32 ++++++++++---------------------- 4 files changed, 32 insertions(+), 39 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 709ae39..2906660 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -85,7 +85,11 @@ The `cheat` command-line tool is organized into several key packages: - Writes to stdout or pager - Handles text formatting and indentation -6. **`internal/repo`**: Git repository management +6. **`internal/installer`**: First-run installer + - Prompts user for initial configuration choices + - Generates default `conf.yml` and downloads community cheatsheets + +7. **`internal/repo`**: Git repository management - Clones community cheatsheet repositories - Updates existing repositories @@ -95,6 +99,7 @@ The `cheat` command-line tool is organized into several key packages: - **Override mechanism**: Local sheets override community sheets with same name - **Tag system**: Sheets can be categorized with tags in frontmatter - **Multiple cheatpaths**: Supports personal, community, and directory-scoped sheets +- **Directory-scoped discovery**: Walks up from cwd to find the nearest `.cheat` directory (like `.git` discovery) ### Sheet Format diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e2f8129..60f72cd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,4 @@ -Contributing -============ +# Contributing Thank you for your interest in `cheat`. @@ -11,4 +10,8 @@ Bug reports are still welcome. If you've found a bug, please open an issue in the [issue tracker][issues]. Before doing so, please search through the existing open issues to make sure it hasn't already been reported. +Feature requests may be filed, but are unlikely to be implemented. The project +is now mature and the maintainer considers its feature set to be essentially +complete. + [issues]: https://github.com/cheat/cheat/issues diff --git a/INSTALLING.md b/INSTALLING.md index 2001d83..cb22d50 100644 --- a/INSTALLING.md +++ b/INSTALLING.md @@ -1,30 +1,29 @@ -Installing -========== +# Installing `cheat` has no runtime dependencies. As such, installing it is generally straightforward. There are a few methods available: -### Install manually -#### Unix-like +## 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.5.1/cheat-linux-amd64.gz \ + && wget https://github.com/cheat/cheat/releases/download/4.7.0/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.5.1`) and the archive +You may need to need to change the version number (`4.7.0`) and the archive (`cheat-linux-amd64.gz`) depending on your platform. See the [releases page][releases] for a list of supported platforms. -#### Windows +### Windows On Windows, download the appropriate binary from the [releases page][releases], unzip the archive, and place the `cheat.exe` executable on your `PATH`. -### Install via `go install` +## Install via `go install` If you have `go` version `>=1.17` available on your `PATH`, you can install `cheat` via `go install`: @@ -32,7 +31,7 @@ If you have `go` version `>=1.17` available on your `PATH`, you can install go install github.com/cheat/cheat/cmd/cheat@latest ``` -### Install via package manager +## Install via package manager Several community-maintained packages are also available: Package manager | Package(s) @@ -43,8 +42,6 @@ docker | [docker-cheat][pkg-docker] nix | [nixos.cheat][pkg-nix] snap | [cheat][pkg-snap] - - ## Configuring Three things must be done before you can use `cheat`: 1. A config file must be generated @@ -56,7 +53,7 @@ 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 ### +### 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 @@ -72,8 +69,8 @@ export CHEAT_CONFIG_PATH="~/.dotfiles/cheat/conf.yml" [community]: https://github.com/cheat/cheatsheets/ [pkg-aur-cheat-bin]: https://aur.archlinux.org/packages/cheat-bin [pkg-aur-cheat]: https://aur.archlinux.org/packages/cheat -[pkg-brew]: https://formulae.brew.sh/formula/cheat +[pkg-brew]: https://formulae.brew.sh/formula/cheat [pkg-docker]: https://github.com/bannmann/docker-cheat -[pkg-nix]: https://search.nixos.org/packages?channel=unstable&show=cheat&from=0&size=50&sort=relevance&type=packages&query=cheat +[pkg-nix]: https://search.nixos.org/packages?channel=unstable&show=cheat&from=0&size=50&sort=relevance&type=packages&query=cheat [pkg-snap]: https://snapcraft.io/cheat [releases]: https://github.com/cheat/cheat/releases diff --git a/README.md b/README.md index 2f28f8c..3358086 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ ![Workflow status](https://github.com/cheat/cheat/actions/workflows/build.yml/badge.svg) - -cheat -===== +# cheat `cheat` allows you to create and view interactive cheatsheets on the command-line. It was designed to help remind \*nix system administrators of @@ -13,9 +11,7 @@ remember. Use `cheat` with [cheatsheets][]. - -Example -------- +## Example The next time you're forced to disarm a nuclear weapon without consulting Google, you may run: @@ -42,8 +38,10 @@ tar -xjvf '/path/to/foo.tgz' tar -cjvf '/path/to/foo.tgz' '/path/to/foo/' ``` -Usage ------ +## Installing +For installation and configuration instructions, see [INSTALLING.md][]. + +## Usage To view a cheatsheet: ```sh @@ -107,14 +105,7 @@ Flags may be combined in intuitive ways. Example: to search sheets on the cheat -p personal -t networking --regex -s '(?:[0-9]{1,3}\.){3}[0-9]{1,3}' ``` - - -Installing ----------- -For installation and configuration instructions, see [INSTALLING.md][]. - -Cheatsheets ------------ +## Cheatsheets Cheatsheets are plain-text files with no file extension, and are named according to the command used to view them: @@ -143,8 +134,7 @@ 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 ----------- +## Cheatpaths Cheatsheets are stored on "cheatpaths", which are directories that contain cheatsheets. Cheatpaths are specified in the `conf.yml` file. @@ -176,7 +166,7 @@ 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 ### +### 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` directory in the current working directory and its ancestors (similar to how `git` locates @@ -184,8 +174,7 @@ in the current working directory and its ancestors (similar to how `git` locates added to the cheatpaths. This means you can place a `.cheat` directory at your project root and it will be available from any subdirectory within that project. -Autocompletion --------------- +## Autocompletion Shell autocompletion is currently available for `bash`, `fish`, and `zsh`. Copy the relevant [completion script][completions] into the appropriate directory on your filesystem to enable autocompletion. (This directory will vary depending @@ -204,4 +193,3 @@ Additionally, `cheat` supports enhanced autocompletion via integration with [Chroma]: https://github.com/alecthomas/chroma [supported languages]: https://github.com/alecthomas/chroma#supported-languages [fzf]: https://github.com/junegunn/fzf -[go]: https://golang.org