Worktree · XB Field Notes

Use a worktree for a hotfix without disturbing a feature

Sat, 06 Nov 2027 00:00:00 +0000

A hotfix need not displace unfinished feature work from its directory. A linked worktree can start from a chosen release commit while the original directory retains its staged changes, unstaged edits, and untracked files. The workflow succeeds when the fix is tested on the correct baseline and the original work remains intact. Merely creating a second folder does not establish either result.

Pin the release commit, reproduce and fix in the hotfix directory, then verify feature HEAD, staged/unstaged text and untracked notes. Save both untracked review notes and ignored logs outside the checkout before normal removal. The hotfix branch remains.

Choose the baseline before opening another directory

Inspect the current worktree and identify the exact release revision needing the fix. A convenient branch name is not necessarily the deployed revision. If a remote-tracking reference must be refreshed, fetch the intended remote and then record the resolved commit. Fetching updates shared repository references; it does not modify only the directory where the command was entered.

Create the new worktree with an explicit path, branch name, and start point. Using a new hotfix branch avoids competing with a branch already checked out elsewhere. For inspection without intended commits, a detached worktree may be sufficient. Do not use branch-resetting or force options merely because the proposed name already exists; inspect the existing worktree and reference first.

Creation checks out committed content from the selected start point. It does not copy the original directory’s uncommitted feature changes or untracked notes. That separation is useful for reproducing a release problem without accidental fixes or dependencies from the feature workspace. It also means editor buffers and local configuration files do not automatically become available in the new directory.

Reproduce and verify in the actual hotfix tree

Confirm the new HEAD and run the targeted reproduction before changing code. After the repair, run that same check and the relevant broader tests against the hotfix directory. A passing command run from the feature directory is evidence about the wrong checkout. Keep test output associated with the exact commit, directory, and configuration used.

Build outputs placed inside each directory are separate files, but external state may still collide. Two servers can bind the same port, two test suites can write the same database, and shared caches may need correctly keyed entries. A worktree is not a container, virtual machine, or security boundary. Review what build commands execute and which resources they reach before running unfamiliar branch code.

Stage only the intended fix and inspect its diff before committing. The new commit is visible through the shared object database, but the original feature branch and its index need not move. Verify those unchanged states explicitly when preservation matters. Local availability also does not publish the branch or deploy the repair; distribution remains a separate authorized step.

When it breaks

The directory name can suggest a release while its HEAD actually points elsewhere. Check the resolved revision instead of trusting a folder label. Another common mistake is treating shared repository configuration as worktree-private configuration. A setting changed for a hotfix can affect other worktrees, even though their checked-out files remain untouched.

When finished, inspect the linked worktree’s status, untracked files, and valuable ignored outputs. Ordinary status omits ignored files; a clean tracked diff is not proof that the directory contains nothing worth saving. Keep required logs or artifacts outside the directory before removal. Stop processes still using it, because a clean Git status says nothing about running servers or open files.

Use normal git worktree remove on the confirmed path. It refuses ordinary dirty or untracked work rather than silently treating it as disposable. Investigate that refusal instead of routinely adding force. The command removes the linked checkout and its registration, not its branch. Prune is for stale administrative records whose directories are missing, not a command to delete active workspaces.

Check it quickly

Run this on a POSIX system with Python 3 and Git 2.28 or newer. The temporary repository excludes personal Git configuration and inherited Git routing, disables hooks and signing, and has no remote. The feature directory deliberately contains three kinds of unfinished work. The hotfix test first fails, then passes after a one-line repair.

import os
import subprocess
import sys
import tempfile
from pathlib import Path

env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
env.update(GIT_CONFIG_NOSYSTEM="1", GIT_CONFIG_GLOBAL=os.devnull)
with tempfile.TemporaryDirectory(prefix="git-hotfix-demo-") as directory:
 root = Path(directory)
 feature, hotfix = root / "feature", root / "hotfix"
 feature.mkdir()
 def git(tree, *args, check=True):
 return subprocess.run(
 ["git", "-c", "user.name=Hotfix Example",
 "-c", "user.email=hotfix@example.invalid",
 "-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", *args],
 cwd=tree, env=env, text=True, capture_output=True, check=check,
 )
 def test():
 return subprocess.run([sys.executable, "-B", "-c",
 "from calc import double; assert double(4) == 8"],
 cwd=hotfix, text=True, capture_output=True)
 git(feature, "init", "-q", "-b", "feature")
 (feature / "calc.py").write_text("def double(n):\n return n * 2 + 1\n")
 (feature / "draft.txt").write_text("base\n")
 (feature / ".gitignore").write_text("ignored.log\n")
 git(feature, "add", "calc.py", "draft.txt", ".gitignore")
 git(feature, "commit", "-qm", "release baseline")
 baseline = git(feature, "rev-parse", "HEAD").stdout.strip()
 (feature / "draft.txt").write_text("staged\n")
 git(feature, "add", "draft.txt")
 (feature / "draft.txt").write_text("unstaged\n")
 (feature / "idea.txt").write_text("untracked idea\n")
 git(feature, "worktree", "add", "-qb", "hotfix", str(hotfix), baseline)
 print("clean-baseline:", git(hotfix, "rev-parse", "HEAD").stdout.strip() == baseline
 and (hotfix / "draft.txt").read_text() == "base\n"
 and not (hotfix / "idea.txt").exists())
 broken = test()
 print("regression-reproduced:", broken.returncode != 0 and "AssertionError" in broken.stderr)
 (hotfix / "calc.py").write_text("def double(n):\n return n * 2\n")
 fixed = test()
 assert fixed.returncode == 0 and not fixed.stderr, fixed
 git(hotfix, "add", "calc.py")
 git(hotfix, "commit", "-qm", "fix double")
 fixed_commit = git(hotfix, "rev-parse", "HEAD").stdout.strip()
 print("feature-preserved:", git(feature, "rev-parse", "HEAD").stdout.strip() == baseline
 and git(feature, "symbolic-ref", "--short", "HEAD").stdout.strip() == "feature"
 and git(feature, "show", ":draft.txt").stdout == "staged\n"
 and (feature / "draft.txt").read_text() == "unstaged\n"
 and (feature / "idea.txt").read_text() == "untracked idea\n")
 artifact = hotfix / "review-notes.txt"
 artifact.write_text("reviewed\n")
 refused = git(feature, "worktree", "remove", str(hotfix), check=False)
 print("dirty-removal-refused:", refused.returncode != 0 and artifact.exists())
 saved = root / "saved-review.txt"
 artifact.rename(saved)
 ignored = hotfix / "ignored.log"
 ignored.write_text("useful build log\n")
 print("ordinary-status-hides-ignored:", not git(hotfix, "status", "--porcelain").stdout
 and "ignored.log" in git(hotfix, "status", "--short", "--ignored").stdout)
 saved_log = root / "saved-build.log"
 ignored.rename(saved_log)
 git(feature, "worktree", "remove", str(hotfix))
 print("checkout-removed-branch-kept:", not hotfix.exists()
 and git(feature, "rev-parse", "hotfix").stdout.strip() == fixed_commit)
 print("review-notes-preserved:", saved.read_text() == "reviewed\n"
 and saved_log.read_text() == "useful build log\n")

All seven observations should print True. The hotfix starts from committed baseline content, reproduces the bug, and leaves every original feature state unchanged. An untracked review note prevents removal until it is moved outside the linked checkout. An ignored log is invisible to ordinary status but visible with --ignored; it is saved separately too. Normal removal then succeeds while the hotfix branch, saved note, and log remain. The outer temporary-directory cleanup intentionally discards all demonstration data only after these checks.

Sources

Git worktree reference, explicit creation, checkout safeguards, removal, and pruning, checked 2026-10-15.
Git status reference, staged versus working-tree changes and untracked or ignored files, checked 2026-10-15.

Git worktrees share a repository, not a checkout

Mon, 26 Jul 2027 00:00:00 +0000

A linked worktree gives one Git repository another working directory, with its own checked-out state. That lets a feature, release, or review stay open alongside other work without repeatedly replacing the same files. The useful boundary is separate working files and staging, not complete isolation. Objects, many references, and ordinary repository configuration are shared, so operations need to respect both the local workspace and the common repository.

Linked worktrees share objects, branch/tag references, default repository configuration and stash. Each retains HEAD, index, working files and operation state such as refs/bisect. The review commit becomes readable from main without changing its staged text.

Identify the state that belongs to each checkout

Each worktree has its own HEAD and index. A staged change in one directory does not appear in the other’s index, and editing a tracked file does not edit its counterpart next door. Committing in a linked worktree normally advances its selected branch. That new object and shared branch reference are immediately available to Git commands run from the other worktrees, without a fetch between them.

The linked directory’s .git entry is normally a file pointing to its administrative directory. The checked-out source files live at the path chosen for the worktree, not inside the administrative .git/worktrees entry. Tools that assume .git must be a directory can fail here. Ask Git for --git-common-dir, --absolute-git-dir, or --git-path index instead of constructing internal paths yourself.

Objects are shared, but working files and build outputs still consume space separately. A second checkout is not another complete object database, yet it is not a zero-copy view of every source and generated file. Estimate disk use from the actual checkout and build requirements, especially when several release versions remain open.

Shared does not mean every item is shared

Local branches and tags generally belong to the common repository. HEAD and operation-specific state belong to a worktree; some references, including those under refs/bisect, are also per-worktree. Treating every reference as either globally shared or entirely local produces incorrect tooling. Use Git commands to resolve the relevant reference in the intended worktree.

Repository configuration is shared by default. A git config --local change made while standing in the review directory can therefore affect the feature directory too. Git supports explicitly enabled worktree-specific configuration, but enabling that extension is a repository configuration change requiring its documented migration rules. Do not silently assume ordinary local configuration already means local to this checkout.

Likewise, a shared stash list is not a private scratch area for one worktree. Name and inspect any saved work before applying or dropping it. Separate source directories also do not automatically isolate network ports, databases, external caches, or credentials used by commands launched from them.

When it breaks

By default, Git refuses to check out the same local branch in two worktrees. This protects separate indexes and files from competing updates to one moving reference. It is a safeguard that force options can override, not an unbreakable storage law. Prefer a distinct branch for independent changes or a detached checkout for inspecting the same commit, instead of bypassing the guard as routine setup.

A detached checkout has no local branch advancing with new commits. If its experimental work must survive removal, give the desired commit a branch name first. Removing a worktree does not automatically delete its branch, and pruning stale administration is not the same as deleting a live checkout. Use the operation that matches the actual state.

For moves, prefer git worktree move where supported; it cannot move the main worktree or linked worktrees containing submodules. Use repair to reconnect a manually moved checkout. A temporarily unavailable removable volume is not necessarily abandoned. Locking that worktree can prevent its registration from being pruned while it is offline. Avoid manually editing administrative files as a general recovery recipe.

Check it quickly

Run this on a POSIX system with Python 3 and Git 2.28 or newer. The temporary repository excludes inherited Git routing and personal configuration, uses example identity, and disables hooks and signing. The only configuration written is a synthetic demonstration key. Two tracked versions are staged independently, then a linked commit becomes visible from the main directory.

import os
import subprocess
import tempfile
from pathlib import Path

env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
env.update(GIT_CONFIG_NOSYSTEM="1", GIT_CONFIG_GLOBAL=os.devnull)
with tempfile.TemporaryDirectory(prefix="git-worktree-state-") as directory:
 root = Path(directory)
 main, review, detached = root / "main", root / "review", root / "detached"
 main.mkdir()
 def git(tree, *args, check=True):
 return subprocess.run(
 ["git", "-c", "user.name=Worktree Example",
 "-c", "user.email=worktree@example.invalid",
 "-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", *args],
 cwd=tree, env=env, text=True, capture_output=True, check=check,
 )
 git(main, "init", "-q", "-b", "main")
 (main / "note.txt").write_text("base\n")
 git(main, "add", "note.txt")
 git(main, "commit", "-qm", "base")
 git(main, "worktree", "add", "-qb", "review", str(review), "HEAD")
 common = [(tree / git(tree, "rev-parse", "--git-common-dir").stdout.strip()).resolve()
 for tree in (main, review)]
 indexes = [(tree / git(tree, "rev-parse", "--git-path", "index").stdout.strip()).resolve()
 for tree in (main, review)]
 print("shared-common-dir:", common[0] == common[1])
 print("separate-indexes:", indexes[0] != indexes[1])
 (main / "note.txt").write_text("main staged\n")
 git(main, "add", "note.txt")
 (review / "note.txt").write_text("review staged\n")
 git(review, "add", "note.txt")
 print("independent-staging:", git(main, "show", ":note.txt").stdout == "main staged\n"
 and git(review, "show", ":note.txt").stdout == "review staged\n")
 git(main, "config", "--local", "demo.shared", "visible")
 print("shared-local-config:", git(review, "config", "--get", "demo.shared").stdout.strip() == "visible")
 git(review, "commit", "-qm", "review change")
 print("commit-visible-from-main:", git(main, "show", "review:note.txt").stdout == "review staged\n")
 print("main-staging-unchanged:", git(main, "show", ":note.txt").stdout == "main staged\n"
 and (main / "note.txt").read_text() == "main staged\n")
 duplicate = git(main, "worktree", "add", str(root / "duplicate"), "main", check=False)
 print("duplicate-branch-refused:", duplicate.returncode != 0)
 git(main, "worktree", "add", "-q", "--detach", str(detached), "main")
 print("detached-copy-allowed:", git(detached, "symbolic-ref", "-q", "HEAD", check=False).returncode == 1)
 git(main, "worktree", "remove", str(review))
 git(main, "worktree", "remove", str(detached))

All eight checks should print True. The administrative paths establish a common repository and separate indexes. Each index retains its own staged text, while the synthetic configuration and committed review branch are shared. A duplicate attached branch is rejected, but a detached checkout of the same commit is allowed. The experiment removes only its clean linked checkouts; Python then cleans the disposable main directory.

Sources

Git worktree reference, shared state, per-worktree state, safeguards, and lifecycle commands, checked 2026-10-15.
Git repository layout, linked administrative directories, common storage, and index placement, checked 2026-10-15.

Worktree · XB Field Notes

Use a worktree for a hotfix without disturbing a feature

Choose the baseline before opening another directory

Reproduce and verify in the actual hotfix tree

When it breaks

Check it quickly

Further reading

Sources

Git worktrees share a repository, not a checkout

Identify the state that belongs to each checkout

Shared does not mean every item is shared

When it breaks

Check it quickly

Further reading

Sources