Skip to content

Add git worktree safety guidance to AGENTS.md#2829

Open
vcolin7 wants to merge 2 commits into
mainfrom
vcolin7/agents-worktree-stash-warning
Open

Add git worktree safety guidance to AGENTS.md#2829
vcolin7 wants to merge 2 commits into
mainfrom
vcolin7/agents-worktree-stash-warning

Conversation

@vcolin7
Copy link
Copy Markdown
Contributor

@vcolin7 vcolin7 commented Jun 5, 2026

What does this PR do?

Documents a git stash hazard for contributors who work in linked git worktrees. When multiple worktrees share one repository common git directory, Git stores stash entries in the shared refs/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:

  • Adds a new Git Worktree Safety subsection under "Git Workflow and Automation" explaining the problem and recommending safer alternatives (git diff <ref>, a throwaway git worktree add of the base branch, and explicit staging with git add -p / specific paths instead of git add -A).
  • Adds one concise bullet to the top-level "Don't" list.

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

  • Required for All PRs
    • Read contribution guidelines
    • PR title clearly describes the change
    • Commit history is clean with descriptive messages (cleanup guide)
    • Added comprehensive tests for new/modified functionality (N/A - docs-only change)
    • Created a changelog entry if the change falls among the following: new feature, bug fix, UI/UX update, breaking change, or updated dependencies (N/A - internal contributor documentation only)
  • For MCP tool changes: N/A - no tool changes in this PR

Invoking Livetests

Copilot submitted PRs are not trustworthy by default. Users with write access 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.

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>
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 stash is unsafe with linked worktrees and suggesting alternatives.
  • Add a new item to the top-level “Don’t” list warning against git stash in linked worktrees.

Comment thread AGENTS.md Outdated
@github-project-automation github-project-automation Bot moved this from Untriaged to In Progress in Azure MCP Server Jun 5, 2026
@JasonYeMSFT
Copy link
Copy Markdown
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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

4 participants