iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Git linked worktrees give parallel tasks separate checked-out files, indexes, and HEADs while sharing much of the underlying repository state. That makes separate branches useful for concurrent work, but it does not automatically isolate an agent’s session data, project configuration, or sandbox. The distinction matters when one Codex TUI session is running in the original checkout and another starts in a fresh worktree.
What Git shares—and what each worktree keeps private
Git describes git worktree as a way to “Manage multiple working trees attached to the same repository.” The original checkout is the main worktree; additional checkouts are linked worktrees. A linked worktree has its own working directory and private administrative area, while its .git file points to that administration and Git connects it to the repository’s shared common directory.
The practical rule is that a separate directory is not a separate repository. Git shares most repository data, including the object database and ordinary refs, while maintaining selected state separately for each worktree. The worktree documentation and repository layout documentation describe the split.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitches| State | Default behavior across linked worktrees |
|---|---|
| Checked-out files | Each worktree has its own working directory, so edits in one directory do not directly change the other directory’s files. |
| Index | Each worktree has its own index, recording its staged state. |
| HEAD | Each worktree has its own HEAD, so worktrees can be checked out at different commits or branches. |
| Object database | Shared by the repository. |
| Refs | Most refs are shared. The documented exceptions are refs/bisect, refs/worktree, and refs/rewritten. |
| Repository config | Shared by default; Git supports worktree-specific configuration through extensions.worktreeConfig and git config --worktree. |
For scripts, do not assume a Git metadata file lives beneath a particular worktree’s .git directory. For example, git rev-parse --git-path HEAD resolves the current worktree’s private HEAD, while git rev-parse --git-path refs/heads/<branch> resolves an ordinary branch ref through the common directory. Use git rev-parse --git-path to locate paths, rather than hard-coding assumptions about $GIT_DIR or $GIT_COMMON_DIR.
#1 Best Overall
How to set up parallel Git worktrees safely
-
Create a separate branch and worktree for each concurrent task. For example,
git worktree add -b agent/task-a ../task-a maincreates a new branch and checks it out in../task-a, starting frommain. Choose a starting branch or commit that exists in your repository. -
Check the inventory with
git worktree list. For scripts that need a stable, parseable listing, usegit worktree list --porcelain.Rank #2
-
Keep each task on its own branch. By default Git refuses to check out a branch that is already checked out in another worktree. Avoid routine use of
--forceto bypass this safeguard: separate directories do not make concurrent work on one branch’s ref independent.Free tools Windows power users keep installed
One-click scans. No signup required.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Use Git commands rather than editing metadata files directly. Resolve a metadata path with
git rev-parse --git-path; update refs or configuration through commands such asgit update-reforgit configwhere appropriate.
Why a second agent session may still share or affect state
Git’s isolation guarantees apply to Git’s working trees and metadata model. They do not specify where an agent application stores its session registry, how it resolves project-level configuration or hooks, or what a sandbox allows it to write. A second agent session can therefore encounter shared or unexpectedly resolved application state even though it runs from a different worktree.
Two open Codex CLI issue reports illustrate why the distinction deserves attention, but neither establishes universal Codex behavior or a confirmed general fix. One user report describes a new worktree session being interrupted while another session was active in the base worktree, and says a later launch read a project hooks configuration path from the base worktree. It is a reported observation, not proof of root cause or current status: Codex CLI issue report.
A separate report specifies Codex CLI 0.158.0 on macOS and a particular workspace-write layout. It describes the linked worktree’s private administration as protected while the shared common directory remained writable, raising a concern about shared hooks or configuration affecting later Git use. Treat those details as specific to that report, not as a statement about other versions, platforms, or layouts: Codex CLI issue report.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- Use distinct branches and worktree paths for parallel tasks.
- Review project hooks and configuration with the understanding that Git config is shared by default.
- Check the agent application’s own session and sandbox behavior separately; Git worktrees alone cannot prove that it is isolated.
When worktree-specific Git configuration is appropriate
If a setting should differ between linked worktrees, Git supports worktree-specific configuration. Enable the extensions.worktreeConfig repository extension and use git config --worktree to write a setting for the current worktree. This is a deliberate change to the repository’s configuration model, not the default; consult the Git worktree documentation for compatibility and migration considerations before enabling it, especially if people or automation use older Git versions.
Best Value
Move, remove, or recover a worktree
- Normal removal: use
git worktree remove <path>to remove a linked worktree through Git’s managed workflow. - Directory deleted manually: run
git worktree pruneif stale administration remains. - Move a worktree: use
git worktree moverather than moving its directory by hand. If a manual move breaks the association, usegit worktree repair. - Storage may go offline: use
git worktree lockso Git does not prune the worktree’s metadata while its location is unavailable.
These commands and their options are documented in Git’s worktree reference.
Choose worktrees or a separate clone based on the isolation you need
Linked worktrees are a good fit when tasks need separate files, indexes, and branch checkouts but can share the repository’s object database and most refs. They are not a boundary for every kind of state. If the requirement is broader than Git’s documented per-worktree separation—such as isolating an application’s configuration or sandbox—verify that application’s behavior or choose an arrangement that provides the needed isolation. Git’s worktree documentation describes linked worktrees, not agent-session isolation.
Quick Recap
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.
