Conversation
- Add docs/USAGE.md with comprehensive command reference, all flags, example output, and full configuration documentation - Add docs/HOOKS.md with dedicated hooks guide covering all hook types, environment variables, worktree index, and examples - Streamline README.md to high-level overview with deep links to docs - Prioritize Homebrew installation, collapse alternatives into details - Simplify CONTRIBUTING.md to essentials with link to architecture - Trim docs/ARCHITECTURE.md to technical implementation details only Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThis PR reorganizes and expands project documentation: updates contributor guidance, streamlines the README, restructures ARCHITECTURE.md, and adds comprehensive docs for Hooks and Usage plus an example hook script. Changes
Sequence Diagram(s)(omitted) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧹 Recent nitpick comments
|
- Add Documentation section outlining doc structure and update policy - Remove make install and make build-all (not commonly used) - Add internal/userconfig/ package (was missing) - Add Config Layering design pattern - Remove Version Injection pattern (implementation detail) - Make descriptions more terse Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
![coderabbitai[bot]](https://waps.l3s.uni-hannover.de/live/im_/https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/HOOKS.md`:
- Around line 1-368: The docs reference a non-existent example script
"show-info.sh" (mentioned under "Examples" and as examples/hooks/show-info.sh);
fix by either adding the missing script file at examples/hooks/show-info.sh
implementing the shown info hook behavior (use WT_INDEX to print URL/ports) or
remove the "### show-info.sh" example and any other references to
examples/hooks/show-info.sh in HOOKS.md so the Examples list only contains real
files (ensure the Examples list and "Example hook scripts are available in
[examples/hooks/]" section stay consistent).
🧹 Nitpick comments (1)
docs/USAGE.md (1)
1-540: Comprehensive and well-organized usage documentation.This guide thoroughly documents all commands with clear syntax, flags, behavior descriptions, and practical examples. The configuration reference is complete and easy to navigate. The structure makes it easy for users to find exactly what they need.
Consider adding language identifiers to the example output fenced code blocks to satisfy markdown linters:
📝 Optional markdown linting fixes
The static analysis tool flags three fenced code blocks without language specifiers. While these are example outputs (not code), you can add
textorconsoleidentifiers to satisfy linters:Line 106-112:
-``` +```text NAME INDEX BRANCH STATUS * feature-auth 1 feature-auth ↑2 [in_progress]Line 147-156:
-``` +```text ================================================================================ * feature-authLine 370-372:
-``` +```text wt version 1.2.3
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
CONTRIBUTING.mdREADME.mddocs/ARCHITECTURE.mddocs/HOOKS.mddocs/USAGE.md
🧰 Additional context used
🧠 Learnings (8)
📚 Learning: 2026-01-13T19:27:50.183Z
Learnt from: CR
Repo: agarcher/wt PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-13T19:27:50.183Z
Learning: Set version at build time via LDFLAGS: -X github.com/agarcher/wt/internal/commands.Version=$(VERSION)
Applied to files:
CONTRIBUTING.mddocs/ARCHITECTURE.md
📚 Learning: 2026-01-13T19:27:50.183Z
Learnt from: CR
Repo: agarcher/wt PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-13T19:27:50.183Z
Learning: Never squash or rebase on merge; always use 'gh pr merge --merge' for merging pull requests
Applied to files:
CONTRIBUTING.md
📚 Learning: 2026-01-13T19:27:50.183Z
Learnt from: CR
Repo: agarcher/wt PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-13T19:27:50.183Z
Learning: Each worktree should get a stable numeric index (1+) stored in .git/worktrees/<name>/wt-index for port offsets and resource isolation
Applied to files:
docs/USAGE.mdREADME.mddocs/ARCHITECTURE.mddocs/HOOKS.md
📚 Learning: 2026-01-13T19:27:50.183Z
Learnt from: CR
Repo: agarcher/wt PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-13T19:27:50.183Z
Learning: Hooks should receive standardized environment variables: WT_NAME, WT_PATH, WT_BRANCH, WT_REPO_ROOT, WT_WORKTREE_DIR, WT_INDEX
Applied to files:
docs/USAGE.mdREADME.mddocs/ARCHITECTURE.mddocs/HOOKS.md
📚 Learning: 2026-01-13T19:27:50.183Z
Learnt from: CR
Repo: agarcher/wt PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-13T19:27:50.183Z
Learning: The binary should output paths; shell wrapper function (wt()) generated by 'wt init <shell>' should handle the actual cd command to solve subprocess directory change limitation
Applied to files:
README.mddocs/ARCHITECTURE.md
📚 Learning: 2026-01-13T19:27:50.183Z
Learnt from: CR
Repo: agarcher/wt PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-13T19:27:50.183Z
Learning: Entry point for the application is cmd/wt/main.go which delegates to commands.Execute()
Applied to files:
docs/ARCHITECTURE.md
📚 Learning: 2026-01-13T19:27:50.183Z
Learnt from: CR
Repo: agarcher/wt PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-13T19:27:50.183Z
Learning: Git worktree command wrapping and porcelain output parsing should be implemented in internal/git/
Applied to files:
docs/ARCHITECTURE.md
📚 Learning: 2026-01-13T19:27:50.183Z
Learnt from: CR
Repo: agarcher/wt PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-13T19:27:50.183Z
Learning: Determine if running in main repository vs worktree by checking if .git is a file (worktree) or directory (main repo)
Applied to files:
docs/ARCHITECTURE.md
🪛 markdownlint-cli2 (0.18.1)
docs/USAGE.md
106-106: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
147-147: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
370-370: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (4)
CONTRIBUTING.md (1)
1-55: LGTM! Clear and practical contributor guidelines.The updated structure with build/test/lint instructions and the explicit merge commit requirement aligns well with the project's workflow. The instructions are actionable and easy to follow.
docs/ARCHITECTURE.md (1)
1-100: Well-structured technical documentation.The architecture doc now focuses appropriately on implementation details after moving configuration and hooks documentation to dedicated guides. The updated diagram clearly shows the component relationships, and the new Output Conventions section helpfully explains the stdout/stderr separation that enables shell integration.
README.md (1)
1-159: Excellent restructure - README is now concise and navigable.The streamlined README effectively serves as a high-level overview with appropriate deep links to detailed documentation. The installation flow is clear, and the command reference table provides quick navigation to comprehensive usage docs.
However, verification of internal documentation link targets (docs/USAGE.md command anchors, configuration sections, and docs/HOOKS.md) requires direct access to the repository, which could not be completed. Manual verification is recommended to ensure all referenced documentation files and anchor targets exist as expected.
docs/USAGE.md (1)
26-26: No action required. All HOOKS.md anchor targets referenced from USAGE.md exist and use consistent heading formats (level 3 headings for hook types, level 2 for Worktree Index).Likely an incorrect or invalid review comment.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
- Create examples/hooks/show-info.sh referenced in docs/HOOKS.md - Add example showing wt config --global --unset in docs/USAGE.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/USAGE.mdwith comprehensive command reference including all flags, example output, and full configuration documentationdocs/HOOKS.mdwith dedicated hooks guide covering all hook types, environment variables, worktree index system, and examplesREADME.mdto high-level overview with deep links to detailed docsCONTRIBUTING.mdto essentials with link to architecture docsdocs/ARCHITECTURE.mdto technical implementation details only (remove duplicated config/hook info)Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.