Add git worktree safety guidance to AGENTS.md#2829
Open
vcolin7 wants to merge 2 commits into
Open
Conversation
Warn against using git stash in linked worktrees that share a common .git directory, since stash entries live in the shared refs/stash and collide across concurrent worktrees, risking clobbered edits. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates contributor guidance in AGENTS.md to document a safety hazard when using git stash across multiple linked worktrees that share a common .git directory, and provides safer workflow alternatives to avoid accidentally applying/dropping the wrong changes.
Changes:
- Add a new “Git Worktree Safety” subsection under “Git Workflow and Automation” describing why
git stashis unsafe with linked worktrees and suggesting alternatives. - Add a new item to the top-level “Don’t” list warning against
git stashin linked worktrees.
JasonYeMSFT
approved these changes
Jun 5, 2026
Member
|
Is this issue surfaced in an agent session? For a human author, when they see the poped change, they should notice that the diff is not what they expect, right? |
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
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 does this PR do?
Documents a
git stashhazard for contributors who work in linked git worktrees. When multiple worktrees share one repository common git directory, Git stores stash entries in the sharedrefs/stash, so stash operations from concurrent worktrees share a single stack. A stash created, popped, or dropped in one worktree can therefore apply or restore the wrong changes in another. This caused a real near-miss during parallel work, so this PR adds explicit guidance to steer contributors away from it.The change is documentation-only and edits a single file,
AGENTS.md:git diff <ref>, a throwawaygit worktree addof the base branch, and explicit staging withgit add -p/ specific paths instead ofgit add -A).Spelling was verified with
.\eng\common\spelling\Invoke-Cspell.ps1(passes). No build or tests are needed for a docs-only change.GitHub issue number?
N/A
Pre-merge Checklist
Invoking Livetests
Copilot submitted PRs are not trustworthy by default. Users with
writeaccess to the repo need to validate the contents of this PR before leaving a comment with the text/azp run mcp - pullrequest - live. This will trigger the necessary livetest workflows to complete required validation.