ADR-004: Recursive .cheat Directory Search

Date: 2026-02-15

Status

Accepted

Context

Previously, cheat only checked the current working directory for a .cheat subdirectory to use as a directory-scoped cheatpath. If a user was in ~/projects/myapp/src/handlers/ but the .cheat directory lived at ~/projects/myapp/.cheat, it would not be found. Users requested (#602) that cheat walk up the directory hierarchy to find the nearest .cheat directory, mirroring the discovery pattern used by git for .git directories.

Decision

Walk upward from the current working directory to the filesystem root, and stop at the first .cheat directory found. Only directories are matched (a file named .cheat is ignored).

Stop at first .cheat found

Rather than collecting multiple .cheat directories from ancestor directories:

• Matches .git discovery semantics, which users already understand
• Fits the existing single-cheatpath-named-"cwd" code without structural changes
• Avoids precedence and naming complexity when multiple .cheat directories exist in the ancestor chain
• cheat already supports multiple cheatpaths via conf.yml for users who want that; directory-scoped .cheat serves the project-context use case

Walk to filesystem root (not $HOME)

Rather than stopping the search at $HOME:

• Simpler implementation with no platform-specific home-directory detection
• Supports sysadmins working in /etc, /srv, /var, or other paths outside $HOME
• The boundary only matters on the failure path (no .cheat found anywhere), where the cost is a few extra stat calls
• Security is not a concern since cheatsheets are display-only text, not executable code

Consequences

Positive

• Users can place .cheat at their project root and it works from any subdirectory, matching their mental model
• No configuration changes needed; existing .cheat directories continue to work identically
• Minimal code change (one small helper function)

Negative

• A .cheat directory in an unexpected ancestor could be picked up unintentionally, though this is unlikely in practice and matches how .git works

Neutral

• The cheatpath name remains "cwd" regardless of which ancestor the .cheat was found in

Alternatives Considered

1. Stop at $HOME

Rejected: Adds platform-specific complexity for minimal benefit. The only downside of walking to root is a few extra stat calls on the failure path.

2. Collect multiple .cheat directories

Rejected: Introduces precedence and naming complexity. Users who want multiple cheatpaths can configure them in conf.yml.

References

• GitHub issue: #602
• Implementation: findLocalCheatpath() in internal/config/new.go