docs: document interrupted-worktree recovery and gitignore dirty-detection#40
Open
baruch wants to merge 1 commit into
Open
docs: document interrupted-worktree recovery and gitignore dirty-detection#40baruch wants to merge 1 commit into
baruch wants to merge 1 commit into
Conversation
…ction Add a "Recovering an interrupted worktree" section to the README covering what happens when a `get` subshell ends abnormally (crash, OOM, closed terminal): the stale owner reservation is self-healed, uncommitted work stays protected, and you recover it via `treehouse status` + `cd`. Flag the two clean-tree cases that are NOT protected -- committed work and gitignored-only changes -- and point to `get --lease` for durable holds. Also clarify, in both the README "Dirty detection" highlight and the AGENTS.md design note, that .gitignore'd files are not counted dirty (so such a worktree can be reused) but are not deleted by the reset, since `git clean -fd` runs without `-x` and respects `.gitignore`. Co-Authored-By: Claude Opus 4.8 <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.
What
Adds user- and agent-facing docs for two behaviors that were previously only
derivable by reading the code.
1. Recovering an interrupted worktree (README)
1. Recovering an interrupted worktree (README)
New "Recovering an interrupted worktree" section covering what happens when
a
treehouse getsubshell ends abnormally — closed terminal, crash, or OOM:self-healed on the next command, and uncommitted work (tracked or
untracked) stays protected from
getreuse,prune, anddestroy.treehouse statusto find thedirtyworktree by path,cdin to resume,treehouse return <path>when done.non-leased worktree — committed work (reclaimed by
git reset --hard,recoverable via
git reflog) and.gitignored-only changes — and pointingto
treehouse get --leasefor durable holds across crashes.2.
.gitignored files vs. dirty detection (README + AGENTS.md)Clarifies a previously-undocumented edge case: ignored files are not counted
as dirty (so a worktree whose only leftover content is ignored can be reused),
but treehouse's reset never deletes them either —
ResetWorktreerunsgit clean -fd(without-x), which respects.gitignore.Why
The dirty-detection note previously said only "untracked files count as dirty."
The crash-recovery flow and the ignored-files nuance are accurate in the code
(
IsDirty,ResetWorktree,healState,Acquire) but were undocumented —exactly the behavior a user relies on when an agent session dies.
Scope
Documentation only — no code changes. Touches
README.mdandAGENTS.md(the design-decisions note;
CLAUDE.mdsymlinks to it). 2 files, +26/−2.