{"slug": "a-gentle-introduction-to-git-worktrees", "title": "A gentle introduction to Git worktrees", "summary": "Git worktrees, a feature available for over a decade, are now being used by AI coding tools to enable multiple agents to work in parallel on local changes without interference, according to a technical explainer. Worktrees allow branches to exist in separate directories from the project root, maintaining full commit history and remote access, though dependencies must be reinstalled per worktree and each branch can only be checked out in one directory at a time.", "body_md": "Git worktrees have been around for over ten years, but if you’re like me, you might not have heard of them until recently. AI coding tools now regularly use worktrees to make local changes in parallel, allowing multiple coding agents to work autonomously without interfering with each other’s work. Once complete, you can then merge those worktrees back into your repository. This allows you to avoid sending code to the cloud while still parallelizing as much work as possible.\n\nWorktrees are an elegant solution to the parallelization problem, although they are frequently misunderstood and, more importantly, poorly explained. This post demystifies worktrees so you can get up and running quickly.\n\n## Creating branches\n\nYou can think of a worktree as a branch that exists in a different location from the project root. It still maintains all of the commit history from the root, it just exists in a different space. You can push and pull from remotes, too. For all intents and purposes, it functions like any other branch in your repository. The only difference is where the files live.\n\nWithout worktrees, you’d create a branch like this:\n\n```\ngit checkout -b feature/name main\n```\n\nThis creates a new branch off of `main`\n\ncalled `feature/name`\n\nin your project root. For example, if your project exists in `~/projects/my-project`\n\n, that’s also where the branch is created. (The project root is also called the *main worktree*.)\n\nIf instead you want to create a worktree with that branch name, you can do so with this command:\n\n```\ngit worktree add ../projects/my-project.worktrees/feature-name -b feature/name main\n```\n\nThis creates the directory `project.worktrees/feature-name`\n\nand creates a branch off of `main`\n\ncalled `feature/name`\n\n. All of your files from `main`\n\nnow exist in this separate directory, and you can `cd`\n\ninto that directory to continue work as usual, with a couple of caveats:\n\n**Dependencies are not shared.** If you are working on a Node.js project, you’ll need to run`npm install`\n\nagain inside the worktree directory. This directory doesn’t have access to the main worktree’s`node_modules`\n\ndirectory, so it needs its own copy. This is true for any projects requiring installation of dependencies to work.**The worktree owns the branch.** Back in your main worktree, you’ll get an error if you try`git checkout feature/name`\n\nbecause every branch can only be checked out to one directory. The worktree directory currently has that branch checked out so no other directory can do so.\n\nOtherwise, you can treat a worktree directory like any other directory with a clone of your repository.\n\n## Directory conventions\n\nThere are two conventions for creating worktree directories:\n\n**Direct sibling.** A lot of tutorials describe creating worktree directories as direct siblings of the main worktree. So if your main worktree is`~/projects/my-project`\n\n, you might create a worktree directory of`~/projects/my-project-feature-name`\n\n.**Shared sibling ancestor.** Some coding agents create a single sibling directory within which all worktree directories are created. For example,`~/projects/my-project.worktrees`\n\ncontains all of the worktree directories related to`~/projects/my-project`\n\n. I prefer this approach and use it in this post.\n\n## Merging changes\n\nHow you merge changes from a worktree back into your main worktree is a matter of preference.\n\n### Pull requests\n\nIf you’re working in a collaborative environment, you might just push your worktree branch to `origin`\n\nand open a pull request. That pull request can then be merged directly into `main`\n\njust like any other pull request. Because a worktree contains a complete copy of your repository, the relationship between the worktree branch and the remote persists.\n\n### Merge locally\n\nIf you’d rather merge changes from your worktree manually, you can do that much the same way you would with any other branch. First, be sure you have all of your changes committed in your worktree. Then, you can merge into the main worktree:\n\n```\n# Go into worktree\ncd ../my-project.worktrees/feature-name\n\n# Rebase on top of main to ensure a clean merge\ngit rebase main\n\n# Go to main worktree\ncd ../my-project\n\n# Merge in your changes\ngit merge feature/name\n```\n\nAt this point, you can decide whether you want to keep the branch and worktree around.\n\n## Cleaning up\n\nWhen you’re done with a worktree, you can remove it:\n\n```\n# Deletes the directory but not the branch\ngit worktree remove ../my-project.worktrees/feature-name\n```\n\nThis physically removes the worktree directory but does not remove the branch. At this point, with the branch no longer checked out in a worktree, you can once again check it out in the main worktree if you’d like.\n\nWhen you’re sure you no longer need the branch, you can delete it as usual:\n\n```\n# Delete the branch\ngit branch -d feature/name\n```\n\n## Other tips\n\nThere are a few other useful things to know about worktrees.\n\n### List all worktrees\n\nTo see all worktrees that currently exist (including the main worktree):\n\n```\ngit worktree list\n```\n\nThis is especially helpful when using AI coding agents who may be creating worktrees without your direct knowledge.\n\n### Fewer characters to type\n\nIf you’d like to type fewer characters, you can set up an alias for `worktree`\n\n:\n\n```\n# Set wt as an alias for worktree\ngit config --global alias.wt worktree\n\n# Much shorter commands\ngit wt add ../myproject.worktrees/ -b feature/name main\ngit wt list\ngit wt remove ../myproject.worktrees/\n```\n\n## Conclusion\n\nGit worktrees are a powerful, underappreciated feature that fit naturally into modern development workflows, especially as AI coding agents become a bigger part of the picture. Once you understand that a worktree is really just a branch checked out to a different directory, the mental model clicks quickly. You get all the benefits of parallel development without shipping your code to a remote service to make it happen.\n\nThe workflow is straightforward: create a worktree for each task, do your work, merge or open a pull request when done, and clean up. Commands like `git worktree list`\n\ngive you visibility into what’s checked out where, and a simple alias like `wt`\n\nkeeps the overhead low. Give worktrees a try next time you need to juggle multiple tasks in the same repository.", "url": "https://wpnews.pro/news/a-gentle-introduction-to-git-worktrees", "canonical_source": "https://humanwhocodes.com/blog/2026/07/introduction-git-worktrees/", "published_at": "2026-07-14 00:00:00+00:00", "updated_at": "2026-07-14 16:25:21.632902+00:00", "lang": "en", "topics": ["developer-tools"], "entities": ["Git"], "alternates": {"html": "https://wpnews.pro/news/a-gentle-introduction-to-git-worktrees", "markdown": "https://wpnews.pro/news/a-gentle-introduction-to-git-worktrees.md", "text": "https://wpnews.pro/news/a-gentle-introduction-to-git-worktrees.txt", "jsonld": "https://wpnews.pro/news/a-gentle-introduction-to-git-worktrees.jsonld"}}