{
    "slug": "git_worktree",
    "term": "Git Worktree",
    "category": "git",
    "difficulty": "intermediate",
    "short": "Checks out multiple branches into separate working directories from one repository, avoiding stash juggling and duplicate clones.",
    "long": "Git worktree lets a single repository have multiple working trees checked out simultaneously, each on its own branch, sharing the same .git object store. Instead of stashing changes to switch branches, or cloning the repo twice to work on a feature and a hotfix in parallel, you run `git worktree add ../hotfix main` and get a separate directory tied to the same repository. Each worktree has its own index, HEAD, and checked-out files, but commits, refs, and objects are shared - so a fetch in one worktree is visible in all of them. Common uses: building a release branch while continuing feature work, running long test suites on one branch while editing another, reviewing a PR branch without disturbing your current state, or letting an editor keep an isolated environment per task. Constraints: the same branch cannot be checked out in two worktrees at once (git refuses to prevent conflicting index states), and a detached HEAD is allowed if you need the same commit in two places. Worktrees are managed with `git worktree list`, `git worktree remove`, and `git worktree prune` to clean up stale administrative entries left when a directory is deleted manually. Linked worktrees store their metadata under .git/worktrees/<name>, and the worktree directory contains a .git file (not folder) pointing back to the main repository. Worktree is faster and lighter than a second clone because objects are not duplicated, but it shares the same submodule and hook configuration, so each worktree is not fully independent. It is a built-in feature since Git 2.5, requires no extra tooling, and pairs well with rebase, bisect, and CI checkout flows where you want a clean tree separate from your daily work.",
    "aliases": [
        "git worktree add",
        "linked worktree",
        "multiple working trees"
    ],
    "tags": [
        "git",
        "worktree",
        "workflow",
        "branching",
        "developer-experience"
    ],
    "misconception": "People assume you must clone a repository again to work on two branches at once. A worktree gives you a second checked-out directory while sharing the same object store, so it is faster and uses far less disk.",
    "why_it_matters": "Stash-and-switch loses context and clones duplicate gigabytes of history; worktrees let you handle a hotfix or review a PR in parallel without disturbing in-progress work.",
    "common_mistakes": [
        "Trying to check out the same branch in two worktrees - git refuses to avoid conflicting index state.",
        "Deleting a worktree directory with rm instead of git worktree remove, leaving stale admin entries that need git worktree prune.",
        "Forgetting that worktrees share hooks, config, and submodule state, expecting full isolation like a separate clone.",
        "Adding worktrees inside the main working tree, causing confusing nested git paths.",
        "Not running git worktree list, so abandoned worktrees accumulate and block branch checkouts."
    ],
    "when_to_use": [
        "Handling an urgent hotfix while keeping a long-lived feature branch checked out.",
        "Running a slow test suite or build on one branch while editing another.",
        "Reviewing a PR branch in a clean directory without stashing current work.",
        "Bisecting or rebasing in an isolated tree so your daily working directory stays stable."
    ],
    "avoid_when": [
        "You need fully isolated config, hooks, or submodule state - a separate clone is cleaner.",
        "Your build writes absolute paths or caches that assume a single working directory.",
        "Disk is tight and you only ever work one branch at a time - the extra checked-out tree is unnecessary.",
        "Tooling cannot handle the .git file pointer used by linked worktrees."
    ],
    "related": [
        "git_stash_advanced",
        "git_workflows_compared",
        "git_bisect",
        "git_submodules"
    ],
    "prerequisites": [
        "git_workflows_compared",
        "git_stash_advanced"
    ],
    "refs": [
        "https://git-scm.com/docs/git-worktree",
        "https://git-scm.com/book/en/v2/Git-Tools-Stashing-and-Cleaning"
    ],
    "bad_code": "# Need to fix a hotfix while mid-feature - stash juggling:\ngit stash push -m 'WIP feature'\ngit checkout main\n# ... make hotfix, commit, push ...\ngit checkout feature/big-refactor\ngit stash pop  # hope nothing conflicts\n\n# Or worse - clone the whole repo again (duplicates all history):\ngit clone git@github.com:org/repo.git ../repo-hotfix  # gigabytes copied",
    "good_code": "# Create a linked worktree on main, sharing the same object store:\ngit worktree add ../repo-hotfix main\ncd ../repo-hotfix\n# ... make hotfix, commit, push - feature work untouched ...\n\n# Inspect and clean up (from any worktree; tree must be clean):\ncd -\ngit worktree list\ngit worktree remove ../repo-hotfix\ngit worktree prune  # clear any stale admin entries\n\n# Detached worktree for reviewing a PR commit without a branch:\ngit worktree add --detach ../pr-review origin/feature-x",
    "quick_fix": "Instead of stashing or re-cloning, run `git worktree add ../hotfix main` to get a separate directory on another branch sharing the same repo, then `git worktree remove` when done.",
    "severity": "info",
    "effort": "low",
    "created": "2026-06-07",
    "updated": "2026-06-07",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/git_worktree",
        "html_url": "https://codeclaritylab.com/glossary/git_worktree",
        "json_url": "https://codeclaritylab.com/glossary/git_worktree.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Git Worktree](https://codeclaritylab.com/glossary/git_worktree) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/git_worktree"
            }
        }
    }
}