Git worktrees share a repository, but not every part of a checkout. Each worktree has its own checked-out files, HEAD, and index; most refs and repository configuration are shared by default. That separation lets parallel tasks work on different branches, but it does not guarantee that an AI tool’s sessions, settings, or sandbox are isolated.
Which Git state is shared between worktrees?
Git describes git worktree as a way to “Manage multiple working trees attached to the same repository.” The main worktree is the original checkout; additional checkouts are linked worktrees. They have separate working directories and per-worktree administrative state, while sharing much of the repository’s data. See the Git worktree documentation.
As an Amazon Associate I earn from qualifying purchases.
| State | Default behavior | What that means |
|---|---|---|
| Checked-out files | Separate by worktree | Edits in one working directory do not automatically change the other worktree’s files. |
HEAD and index |
Per-worktree | Each tree can have its own current commit or branch and its own staging area. |
| Most refs, including ordinary branch refs | Shared | Branches and other shared references are repository-level state, not private copies per directory. |
| Exceptions to shared refs | Per-worktree exceptions include refs/bisect, refs/worktree, and refs/rewritten |
Git documents these exceptions; do not assume every ref is shared or every ref is private. |
| Repository configuration | Shared by default | A setting changed in shared config can affect use from other worktrees. |
The repository’s object database is shared as well, so linked worktrees are not separate repository copies. Git’s repository layout documentation explains the common directory and per-worktree files.
Recommended Free Tools
Why separate directories do not mean separate Git metadata
A linked worktree has a private administrative directory under the repository’s worktrees directory. Its top-level .git is a file pointing to that private administration; a common directory holds shared repository data. Consequently, HEAD and a branch ref can resolve from different administrative locations.
#1 Best Overall
For example, in a linked worktree, git rev-parse --git-path HEAD identifies that worktree’s private HEAD, while git rev-parse --git-path refs/heads/<branch> resolves through the common directory for an ordinary branch ref. Scripts should ask Git to resolve these paths instead of assuming a fixed layout or hard-coding $GIT_DIR or $GIT_COMMON_DIR.
How to organize parallel tasks safely
- Create one worktree and branch per concurrent task. Git normally prevents checking out the same branch in multiple worktrees. Keep that safeguard; using
--forceto bypass it is not a routine way to coordinate concurrent work. Consult the worktree command documentation for the command options. - Inspect worktrees with Git. Use
git worktree listfor a human-readable inventory, orgit worktree list --porcelainwhen a script needs stable, machine-readable output. - Keep scripts independent of Git’s internal layout. Use
git rev-parse --git-path <path>to find administrative paths. Change refs and configuration through commands such asgit update-refandgit config, rather than editing internal files directly. - Decide whether configuration should be shared. Shared repository configuration is the default. To use worktree-specific settings, enable the
extensions.worktreeConfigextension and usegit config --worktree. Check the compatibility and migration guidance in the Git documentation before adopting it, especially if the repository is used with older Git versions. - Use Git’s commands when moving or cleaning up worktrees. Prefer
git worktree movefor a managed move andgit worktree repairif the association needs repair. Usegit worktree removefor ordinary removal. If you deleted a directory manually and stale administration remains, rungit worktree prune. - Lock trees on storage that may be unavailable. If a worktree is on intermittently mounted storage,
git worktree lockprotects its administration from pruning while the directory is unavailable.
What a worktree does—and does not—guarantee for agent sessions
Git’s worktree model describes Git files and repository metadata. It does not define how a particular agent application stores session records, chooses a project configuration file, or applies sandbox boundaries. A separate worktree therefore provides useful checkout and index separation, but it is not proof of application-level isolation.
Rank #2
Public Codex CLI issue reports illustrate why the distinction matters, but they are reports of particular cases, not general product guarantees. One open report describes a user whose new worktree session was interrupted while another session was active in the base worktree; the user also said a later launch read a project hooks configuration path from the base worktree. The report does not establish a confirmed root cause, universal behavior, or current fix status: Codex CLI issue report.
A separate report describes Codex CLI 0.158.0 on macOS in a particular workspace-write layout: the linked worktree’s private administration was protected while its shared common directory remained writable. The concern in that report was that shared hooks or configuration could affect later Git use. This is specific to the reported version, platform, and layout; it should not be generalized to other configurations: Codex CLI issue report.
For parallel agent work, treat Git separation and application isolation as separate checks. Confirm which worktree and branch each process uses, and inspect the tool’s own session, project-configuration, and sandbox behavior rather than inferring it from directory separation alone.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
