How to Update a Git Worktree Branch From Main

To update a Git worktree branch from main while an agent is still working, pause the agent, save its unfinished edits, then run git fetch origin and git merge origin/main inside the agent’s worktree. Resolve any conflicts there before resuming the task. Worktrees have separate working files and indexes but share repository refs, so you can update the agent’s branch without checking out main or changing another worktree’s files. A merge incorporates the selected commits into the current branch; the agent keeps working on that same branch afterward.

Prepare the active worktree

For example, suppose the main checkout is ../app and an agent is working in ../app-auth on branch agent/auth. Run these commands from ../app-auth, not from ../app:

cd ../app-auth
git worktree list
git status --short --branch

git worktree list lets you confirm the path and checked-out branch. git status --short --branch shows changed paths and branch information. If the command reports a different branch, stop and locate the intended worktree before integrating anything.

Pause the agent before touching its files. An agent that is still writing can change a file while you inspect, stage, or resolve it. Record what task it was doing and, after the update, tell it which main changes now affect its work. This is a coordination step, not a Git setting.

Make the worktree clean before the merge. Review the changed files and commit a coherent checkpoint on the agent branch, or stash the unfinished edits. Select files deliberately for a checkpoint; git add -A may include unrelated generated or untracked files. If the current changes are too incomplete for a commit, a stash saves local modifications and rolls them back to HEAD; -u also includes untracked files:

git stash push -u -m "auth task before main update"
git stash list
git status --short --branch

Keep track of the entry you just created. Stash refs are shared by the repository, so another worktree can add an entry before you restore yours; do not assume stash@{0} still names it later. When you restore it, inspect git stash list, apply the intended entry, and resolve any application conflicts. git stash apply leaves the entry available until you explicitly drop it, which is useful while checking the result.

Decide which main you mean

If new commits are on the remote’s main, run this in the agent worktree:

git fetch origin
git log --oneline HEAD..origin/main

git fetch origin updates remote-tracking refs such as origin/main under the remote’s configured fetch rules. It does not, by itself, merge those commits into agent/auth or advance the locally checked-out main branch. The revision range HEAD..origin/main lists commits reachable from origin/main but not from the agent’s current commit. Read that list before deciding whether the update is relevant to the task.

If another worktree already has the desired commits on local main, use main as the merge target instead. Worktrees share that branch ref, so the agent worktree can refer to it directly. If your team uses a different remote or default branch, substitute its actual name; do not assume origin/main exists. For background on the branch and worktree relationship, see Git Worktrees: Why AI Agents Need Them.

Merge main into the agent branch

With a clean agent worktree and the desired remote commits fetched, run:

git merge origin/main

This leaves the branch name in place. If the agent branch has no commits beyond the old main tip, Git can fast-forward it. If both sides have new commits, Git normally records a merge commit when it can combine them. If origin/main is already an ancestor of the agent branch, Git reports that it is up to date.

Prefer this route for an active branch when other people or processes may already refer to its commits. The existing agent commits retain their identities, and the merge records where main entered the branch. The trade-off is an additional merge commit when histories have diverged. The later task merge into main is a separate decision; see How to Merge Work From Parallel AI Agents for that step.

If you stashed edits, restore the correct entry only after the merge completes. For example, once git stash list confirms the entry you intend to restore:

git stash apply 'stash@{0}'
git status --short --branch

Replace stash@{0} if another stash has been added. Check the restored files before dropping the stash. An overlap can produce a conflict during stash application even when the merge itself succeeded.

Resolve a stopped merge

If Git stops on a conflict, keep the agent paused. Run git status to identify unmerged paths, open each affected file, and decide how the main change and the agent’s work should fit together. A conflict marker is a request for a decision; deleting the markers without understanding both sides can leave the task wrong.

After editing a conflicted file, stage that file. Repeat until every unmerged path is resolved, then continue:

git status
git add path/to/resolved-file
git diff --cached --check
git merge --continue

git diff --check reports introduced conflict markers and whitespace errors; --cached checks what is staged. It cannot tell whether the chosen behavior is correct, so review the resolved code and run the project’s relevant checks as well. If the resolution has become unclear, git merge --abort tries to return to the pre-merge state. That recovery is more dependable when the worktree was clean before the merge.

Do not restart the agent in the middle of an unresolved merge. First finish or abort it, then give the agent a concise update: which main commits were integrated, which files needed human decisions, and what still needs verification.

When rebase is the better choice

If the agent branch is private and you want its commits to appear after the latest main commit, use git rebase origin/main, which reapplies the branch’s commits on a new base:

git fetch origin
git rebase origin/main

Do this from a clean agent worktree. Rebase creates replacement commits, so choose it only when nobody else needs to keep working from the branch’s existing commit identities. It may stop more than once because it replays commits in sequence. For each stop, resolve the files, stage them, and run git rebase --continue; use git rebase --abort to return to the original branch state if you need to reconsider. Avoid git rebase --skip unless you have determined that discarding that particular commit is intentional.

A dirty worktree is not a reason to rely automatically on --autostash. Git can stash before a rebase and reapply afterward, but that final application may itself conflict. A deliberate checkpoint or named stash makes the handoff back to the agent easier to inspect. After a successful rebase, if you made a manual stash, check git stash list and apply the intended entry. Resolve any stash-application conflicts, then inspect the restored edits before validation and resuming the agent.

Situation	Practical choice
Branch commits are already shared or another process may depend on them	Merge origin/main
Branch is private and linear history matters	Rebase onto origin/main
Agent has unfinished file edits	Pause it, then checkpoint or stash before either operation
Main changes are only in a local worktree	Integrate main rather than origin/main

Check the branch before the agent continues

After a successful merge or rebase and any stash restoration, inspect the state from the agent worktree:

git status --short --branch
git log --oneline HEAD..origin/main
git diff --stat origin/main...HEAD
git diff
git diff --cached

If origin/main has not moved since your fetch, an empty HEAD..origin/main result means the agent branch contains the fetched main commits. The three-dot diff summarizes committed changes on the agent branch since its common ancestor with origin/main; it excludes unfinished edits restored from a stash. Use git diff to inspect unstaged changes, git diff --cached for staged changes, and inspect any untracked files reported by status. Inspect the full branch diff where the incoming changes touched the same behavior. If you integrated local main, substitute main in the branch comparison commands.

Run the repository’s relevant tests and build checks after resolving conflicts or restoring a stash. Then resume the agent with the updated context. Ask it to account for changed interfaces, tests, or assumptions in its remaining work, and review its next diff as you would any other agent-produced change. The update is complete only when the branch state and the task behavior both make sense.

Where Parallel Code fits

Parallel Code is our free, open-source MIT desktop app for macOS and Linux. It runs several AI coding agents in parallel, each in its own git worktree, and provides a diff-first review surface. The Git merge or rebase still happens on the agent’s branch; separate worktrees make it practical to handle one agent’s update without changing another agent’s working files.

Frequently asked questions

Do I need to update the local main worktree first?

No. If the desired commits are on the remote, fetch them and integrate origin/main directly into the agent branch. Use local main when that branch already points to the commits you want.

Can I merge main while the agent has uncommitted edits?

Git may permit some non-overlapping edits, but a merge with substantial uncommitted work is harder to unwind after a conflict. Pause the agent and commit a checkpoint or stash the edits first; restore a stash after the merge and inspect it for conflicts.

Will updating one worktree update every agent’s files?

No. The worktrees share branch refs and repository data, while each has its own working files and index. Repeat the integration in each agent branch that actually needs the new main commits.

Should I use git pull in the agent worktree?

Use an explicit fetch followed by git merge origin/main or git rebase origin/main when the goal is to bring in main. That makes the source branch and history choice visible; a plain git pull follows the current branch’s configured upstream, which may be the agent branch rather than main.