Add CLI --help examples and scheduling documentation by markcallen · Pull Request #74 · markcallen/cache-cleaner

markcallen · 2026-03-01T08:52:18Z

Summary

Add custom flag.Usage output with Examples sections for:
- dev-cache
- git-cleaner
- mac-cache-cleaner
Add scheduling guide at docs/scheduling.md:
- cron examples for all three tools
- launchd plist example for macOS
- logging recommendations and install/start/unload commands
- note on brew services
Link scheduling guide from root README

Issues

Validation

make test

Copilot

Pull request overview

This PR improves the usability of the project’s three CLI tools by enhancing --help output with real-world examples, and adds centralized documentation for running the tools on schedules (cron/launchd), linked from the root README.

Changes:

Add custom flag.Usage functions to include an “Examples” section in --help for dev-cache, git-cleaner, and mac-cache-cleaner.
Add docs/scheduling.md with cron and macOS launchd scheduling examples plus operational notes.
Link the new scheduling guide from the root README.md.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`dev-cache/main.go`	Adds custom `flag.Usage` output with examples for common workflows.
`git-cleaner/main.go`	Adds custom `flag.Usage` output with scan/clean examples.
`mac-cache-cleaner/main.go`	Adds custom `flag.Usage` output with examples for targets/cleaning.
`docs/scheduling.md`	New scheduling guide covering cron and launchd usage patterns.
`README.md`	Adds a link to the new scheduling documentation.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-01T08:55:18Z

dev-cache/main.go

+func init() {
+	flag.Usage = func() {
+		out := flag.CommandLine.Output()
+		fmt.Fprintf(out, "Usage: dev-cache [flags]\n\nFlags:\n")
+		flag.PrintDefaults()
+		fmt.Fprintf(out, "\nExamples:\n")
+		fmt.Fprintf(out, "  dev-cache                        # Scan default path from config\n")
+		fmt.Fprintf(out, "  dev-cache --scan ~/projects      # Scan specific directory\n")
+		fmt.Fprintf(out, "  dev-cache --clean --yes          # Clean without confirmation\n")
+		fmt.Fprintf(out, "  dev-cache --languages node,rust  # Only node and rust caches\n")
+	}


The custom --help output omits the supported -version/--version option (handled via checkVersionFlag), so users won't discover it from help. Consider adding a short line for -version/--version in the usage output near the flags section.

Copilot · 2026-03-01T08:55:18Z

git-cleaner/main.go

+func init() {
+	flag.Usage = func() {
+		out := flag.CommandLine.Output()
+		fmt.Fprintf(out, "Usage: git-cleaner --scan <directory> [flags]\n\nFlags:\n")
+		flag.PrintDefaults()
+		fmt.Fprintf(out, "\nExamples:\n")
+		fmt.Fprintf(out, "  git-cleaner --scan ~/src         # Scan for .git directories\n")
+		fmt.Fprintf(out, "  git-cleaner --scan ~/src --clean # Optimize with git gc\n")
+	}


The custom --help output omits the supported -version/--version option (handled via checkVersionFlag), so users won't discover it from help. Consider adding a short line for -version/--version in the usage output near the flags section.

Copilot · 2026-03-01T08:55:18Z

mac-cache-cleaner/main.go

+func init() {
+	flag.Usage = func() {
+		out := flag.CommandLine.Output()
+		fmt.Fprintf(out, "Usage: mac-cache-cleaner [flags]\n\nFlags:\n")
+		flag.PrintDefaults()
+		fmt.Fprintf(out, "\nExamples:\n")
+		fmt.Fprintf(out, "  mac-cache-cleaner                         # Scan all targets (dry-run)\n")
+		fmt.Fprintf(out, "  mac-cache-cleaner --clean                 # Run cleanup commands\n")
+		fmt.Fprintf(out, "  mac-cache-cleaner --targets docker,npm    # Specific targets only\n")
+	}


The custom --help output omits the supported -version/--version option (handled via checkVersionFlag), so users won't discover it from help. Consider adding a short line for -version/--version in the usage output near the flags section.

Copilot · 2026-03-01T08:55:18Z

docs/scheduling.md

+0 3 * * 0 /usr/local/bin/dev-cache --scan ~/src --clean --yes >> ~/cache-cleaner.log 2>&1
+0 3 * * 0 /usr/local/bin/git-cleaner --scan ~/src --clean >> ~/cache-cleaner.log 2>&1
+0 3 * * 0 /usr/local/bin/mac-cache-cleaner --clean >> ~/cache-cleaner.log 2>&1


The cron examples use "~/..." paths. Tilde expansion is shell-dependent and is not guaranteed in cron (commonly executed under /bin/sh), so these commands may fail on some systems. Prefer absolute paths or use $HOME for the scan path and log path in the examples.

Suggested change

0 3 * * 0 /usr/local/bin/dev-cache --scan ~/src --clean --yes >> ~/cache-cleaner.log 2>&1

0 3 * * 0 /usr/local/bin/git-cleaner --scan ~/src --clean >> ~/cache-cleaner.log 2>&1

0 3 * * 0 /usr/local/bin/mac-cache-cleaner --clean >> ~/cache-cleaner.log 2>&1

0 3 * * 0 /usr/local/bin/dev-cache --scan "$HOME/src" --clean --yes >> "$HOME/cache-cleaner.log" 2>&1

0 3 * * 0 /usr/local/bin/git-cleaner --scan "$HOME/src" --clean >> "$HOME/cache-cleaner.log" 2>&1

0 3 * * 0 /usr/local/bin/mac-cache-cleaner --clean >> "$HOME/cache-cleaner.log" 2>&1

Copilot · 2026-03-01T08:55:19Z

docs/scheduling.md

+Notes:
+- Update binary paths based on your install location (`which dev-cache`, `which git-cleaner`, `which mac-cache-cleaner`).
+- Keep log redirection enabled for troubleshooting.
+
+## launchd (macOS)
+
+Create `~/Library/LaunchAgents/com.cache-cleaner.weekly.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.cache-cleaner.weekly</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/mac-cache-cleaner</string>
+    <string>--clean</string>
+  </array>


For scheduled runs, environment differs from interactive shells (cron/launchd often have a minimal PATH). Since mac-cache-cleaner can invoke tools like brew/docker/npm from its config, the docs should mention ensuring PATH is set appropriately (e.g., via a PATH=... line in crontab and EnvironmentVariables in the launchd plist). Otherwise scheduled cleanups may fail even if the mac-cache-cleaner binary path is absolute.

docs(cli): add help examples and scheduling guide

ff2f225

markcallen requested a review from Copilot March 1, 2026 08:52

Copilot started reviewing on behalf of markcallen March 1, 2026 08:52 View session

Copilot AI reviewed Mar 1, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add CLI --help examples and scheduling documentation#74

Add CLI --help examples and scheduling documentation#74
markcallen wants to merge 1 commit intomainfrom
feat/5-docs-quickwins

markcallen commented Mar 1, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 1, 2026

Uh oh!

Copilot AI Mar 1, 2026

Uh oh!

Copilot AI Mar 1, 2026

Uh oh!

Copilot AI Mar 1, 2026

Uh oh!

Copilot AI Mar 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

markcallen commented Mar 1, 2026

Summary

Issues

Validation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 1, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants