Skip to content

docs: clarify prune commands#758

Merged
jdx merged 1 commit into
mainfrom
codex/improve-prune-docs
May 20, 2026
Merged

docs: clarify prune commands#758
jdx merged 1 commit into
mainfrom
codex/improve-prune-docs

Conversation

@jdx

@jdx jdx commented May 20, 2026

Copy link
Copy Markdown
Owner

Summary

  • expand aube prune help and docs with lockfile/node_modules behavior
  • point project prune users to aube store prune for global store cleanup
  • document aube store prune scope, cached-index reachability, and hardlink/reflink behavior

Validation

  • cargo build
  • cargo fmt --check
  • ./target/debug/aube prune --help
  • ./target/debug/aube store prune --help

Note

Low Risk
Low risk: changes are limited to CLI help/long-help text and generated docs, with no changes to pruning behavior or data handling.

Overview
Clarifies the CLI/documentation for pruning by expanding aube prune help text to explicitly describe its lockfile-driven cleanup of project node_modules (including virtual-store entries and .bin links) without modifying manifests/lockfiles, and adds an after_long_help hint pointing users to aube store prune for global store cleanup.

Adds detailed long help for aube store prune documenting that it only operates on the global store returned by aube store path, and explains how cached indexes and hardlink vs reflink filesystems affect reachability. Regenerates the CLI docs/JSON to reflect these help updates.

Reviewed by Cursor Bugbot for commit 05ab94a. Bugbot is set up for automated code reviews on this repo. Configure here.

@greptile-apps

greptile-apps Bot commented May 20, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR is a documentation-only change that clarifies the distinction between project-level cleanup (aube prune) and global store cleanup (aube store prune). All changes are limited to help text, doc comments, and generated documentation files — no runtime behavior is modified.

  • aube prune now describes its lockfile-driven algorithm, lists what it removes (stale top-level links, virtual-store entries, dangling .bin links), and explicitly states it does not modify package.json or the lockfile, with a cross-reference to aube store prune.
  • aube store prune gains a detailed description of its scope (the store from aube store path only), its reachability model, and the hardlink-vs-reflink (APFS/btrfs) caveat about link-count reliability.
  • Changes are propagated consistently across aube.usage.kdl, Rust source doc comments, the generated commands.json, and the rendered Markdown docs.

Confidence Score: 5/5

Safe to merge — all changes are help text and documentation strings with no runtime logic touched.

Every change is limited to doc comments, string constants, KDL help blocks, generated JSON, and Markdown files. The wording is accurate and consistent across all eight changed files, and there are no modifications to executable code paths.

No files require special attention.

Important Files Changed

Filename Overview
crates/aube/src/commands/prune.rs Adds AFTER_LONG_HELP constant used by main.rs to attach a cross-reference note to --help output; no logic changes.
crates/aube/src/commands/store.rs Adds doc comments to the Prune variant describing scope, hardlink vs reflink behavior; no logic changes.
crates/aube/src/main.rs Expands Prune doc comments and wires in AFTER_LONG_HELP via #[command(after_long_help)]; no logic changes.
aube.usage.kdl Adds long_help and after_long_help blocks to prune and store prune commands; consistent with Rust source changes.
docs/cli/commands.json Generated file updated with help_long and after_help_long fields; content matches KDL source.
docs/cli/prune.md Generated doc updated with expanded description and cross-reference footer; accurate and consistent.
docs/cli/store/prune.md Generated doc updated with scope, reachability, and filesystem-type caveats; accurate and consistent.
docs/package-manager/dependencies.md Appends a short paragraph clarifying lockfile-only reads and pointing users to store prune for global cleanup.

Reviews (2): Last reviewed commit: "docs: clarify prune commands" | Re-trigger Greptile

@jdx jdx force-pushed the codex/improve-prune-docs branch from 1a33730 to 05ab94a Compare May 20, 2026 15:42
@jdx jdx enabled auto-merge (squash) May 20, 2026 15:47
@jdx jdx merged commit 549d2e7 into main May 20, 2026
18 checks passed
@jdx jdx deleted the codex/improve-prune-docs branch May 20, 2026 15:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant