DOCSEARCHbyAlgolia
Submit Docs

cheat

repository·master·Indexed 11 days ago

https://github.com/cheat/cheat

A command-line tool for creating and viewing interactive, searchable, and tag-based cheatsheets. It supports YAML frontmatter for syntax highlighting, multiple configurable cheatpaths in conf.yml, and directory-scoped .cheat folders for project-specific documentation.

Tokens
10.6K
Snippets
47
Records
62
Agent score
91%

What's inside cheat

  1. Use directory-scoped .cheat directories

    master
    To associate cheatsheets with a specific project, place a .cheat directory in your project root. cheat will search for the nearest .cheat directory in the current working directory or its ancestors (similar to how git works). When found, this directory is temporarily added to your active cheatpaths, allowing project-specific cheatsheets to be available from any subdirectory within that project.

  2. Valid cheatsheet names and naming restrictions

    master

    When using cheat to create, edit, or remove cheatsheets (e.g., via cheat --edit <name> or cheat --rm <name>), the tool enforces specific naming rules to prevent directory traversal and accidental file overwrites.

    Rejected Patterns

    The following patterns are not allowed and will result in an error:

    • Directory traversal: Names containing .. (e.g., ../../etc/passwd).
    • Absolute paths: Names starting with / on Unix (e.g., /etc/passwd).
    • Home directory expansion: Names starting with ~ (e.g., ~/.ssh/config).
    • Hidden files: Names where the filename starts with . (e.g., .secret).
    • Empty names: Providing no name.

    Allowed Patterns

    The following patterns are valid:

    • Simple names: docker, git.
    • Nested paths: docker/compose, lang/go/slice.
    • Current directory references: ./mysheet (Note: while ./ is allowed, the name itself cannot be just . or start with ..).
    # These are allowed:
cheat --edit "docker"
cheat --edit "docker/compose"
cheat --edit "./local"

# These are blocked:
cheat --edit "../../../etc/passwd"
cheat --edit "/etc/passwd"
cheat --edit "~/.ssh/config"
cheat --rm ".."

  3. How directory-scoped `.cheat` directories are discovered

    master

    The cheat tool automatically searches for a directory named .cheat to use as a project-specific cheatpath. This search follows a recursive upward traversal pattern similar to how git discovers .git directories:

    1. Starting from your current working directory, cheat walks up the directory hierarchy.
    2. It stops at the first directory named .cheat it encounters.
    3. The search continues all the way to the filesystem root if no .cheat directory is found.

    Key Behaviors:

    • Directory Only: Only directories named .cheat are matched. A file named .cheat is ignored.
    • Single Match: Only the nearest ancestor .cheat directory is used. It does not collect multiple directories from the ancestor chain.
    • Contextual Scope: This allows you to place a .cheat directory at your project root (e.g., ~/projects/myapp/.cheat) and have it automatically applied even when you are working in deep subdirectories (e.g., ~/projects/myapp/src/handlers/).
    • Internal Name: Regardless of which ancestor directory is found, the cheatpath is internally identified as "cwd".

  4. Configure cheatpaths in conf.yml

    master

    Cheatpaths are the directories where cheat looks for cheatsheets. You can define these directories in your conf.yml file. To see which directories are currently being used as cheatpaths, use the cheat -d command.

    # List all configured cheatpath directories
cheat -d

  5. Format cheatsheets with YAML frontmatter

    master

    Cheatsheets are plain text files. You can include YAML frontmatter at the beginning of the file to define syntax highlighting and tags.

    ---
syntax: bash
tags: [networking, linux, ssh]
---
# Connect to remote server
ssh user@hostname

# Copy files over SSH
scp local_file user@hostname:/remote/path

  6. Create cheatsheets with YAML frontmatter

    master

    Cheatsheets are plain-text files without file extensions. To enable syntax highlighting and metadata, you can add an optional YAML frontmatter header at the top of the file.

    Supported keys:

    • syntax: The name of the lexer to use for syntax highlighting (compatible with Chroma).
    • tags: An array of strings to categorize the cheatsheet.

    Example Cheatsheet Format:

    ---
syntax: javascript
tags: [ array, map ]
---
// To map over an array:
const squares = [1, 2, 3, 4].map(x => x * x);

  7. Install system dependencies for development

    master

    To develop cheat, ensure the following tools are installed and available on your PATH:

    • git
    • go (version 1.19 or higher is recommended)
    • make

    Optional dependencies:

    • docker: For testing in a pristine environment.
    • pandoc: Required if you need to generate man pages.

  8. Configure cheat and the conf.yml file

    master

    On its first run, cheat automatically runs an installer that performs three essential setup steps:

    1. Generates a configuration file (conf.yml).
    2. Configures cheatpaths.
    3. Downloads community cheatsheets.

    After the first run, you can modify the generated conf.yml to customize settings such as colorization or the paginator.

  9. Install cheat manually on Unix-like systems

    master

    On Unix-like systems, you can install cheat by downloading the binary, unzipping it, and moving it to your local bin directory. Note that you may need to adjust the version number and the specific archive name (e.g., cheat-linux-amd64.gz) based on your platform architecture.

    cd /tmp \
  && wget https://github.com/cheat/cheat/releases/download/5.0.0/cheat-linux-amd64.gz \
  && gunzip cheat-linux-amd64.gz \
  && chmod +x cheat-linux-amd64 \
  && sudo mv cheat-linux-amd64 /usr/local/bin/cheat

  10. Install cheat on Windows

    master
    To install on Windows, download the appropriate binary from the official releases page, unzip the archive, and place the cheat.exe executable in a directory that is included in your PATH environment variable.

  11. Development workflow for building and installing `cheat`

    master

    Follow these steps to iterate on the cheat source code:

    1. Modify the source code.
    2. Run tests: make test.
    3. Build the executable: make build. The resulting binary is placed in the dist directory.
    4. Test the new binary: ./dist/cheat <command>.
    5. Install to your PATH: make install.

    Other useful commands:

    • make build-release: Build cross-platform binaries in dist.
    • make clean: Remove the dist directory.
    • make help: List all available make commands.
    make build
dist/cheat <command>
make install

  12. Develop and test `cheat` using Docker

    master

    To test changes in a clean environment, use the provided Alpine-based Docker setup.

    1. Build the container: make docker-setup
    2. Enter the container: make docker-sh. The source code is mounted at /app.
    3. Clean up: make distclean to destroy the container.
    make docker-setup
make docker-sh
make distclean