Git Worktrees for Hotfixes: Choose the Base Before You Branch
Keep unfinished feature work in place while preparing a hotfix. Choose an approved base commit, verify the linked checkout and record which runtime resources it will use.
RB
Imagine you're halfway through a feature on a remote development machine when a bug turns up in the released application. Your checkout contains unfinished edits and a few files Git doesn't track. A second directory sounds ideal for the fix—but starting it from the feature branch's current commit can bring along changes that never belonged in that release.
Create the hotfix worktree from an explicitly approved base commit, give it a new branch, and verify its initial HEAD before editing. Leave the unfinished checkout in place. Git's worktree reference documents creating a linked checkout with -b; omitting the starting commit in that form defaults to the current HEAD. That's convenient only when HEAD is the baseline you intended.
Choose the revision before the directory
For this hypothetical fix, begin with the release record. Which source revision produced the affected artifact, and which branch or revision does your team approve as the fix's starting point? Those may differ if the maintained release branch already contains other accepted fixes. Write down the choice rather than assuming the current main or your feature checkout is correct.
A commit that exists locally is not proof of what is deployed. Match your release metadata and build provenance to the repository, then resolve the approved reference. This example assumes a trusted, ordinary repository with that commit available locally, a maintained Git client, and no special submodule or sparse-checkout setup. Replace the uppercase placeholders before running anything.
# Run from the existing repository's top-level directory.
git --version
git status --short --untracked-files=all
git worktree list
# Replace APPROVED_FIX_BASE with the approved revision or full commit ID.
git rev-parse --verify --end-of-options 'APPROVED_FIX_BASE^{commit}'The rev-parse documentation describes verifying an object and requiring a commit with ^{commit}. Keep the full resolved ID as BASE_COMMIT_ID in your notes. If resolution fails, stop and obtain the intended history through your normal trusted repository workflow. Substituting a nearby-looking revision would change the fix's starting point.
Review important untracked and ignored files separately and keep a recoverable copy where needed. Git status reports file state; it does not back up the contents. A local database, fixture or environment file may matter even when it isn't part of a commit.
Create the checkout, then prove where it starts
Choose an unused sibling path and a new branch name. In the following example, replace BASE_COMMIT_ID with the resolved ID and adapt the names to your repository. Run each step only after the preceding step succeeds.
git worktree add -b hotfix/release-fix ../project-hotfix BASE_COMMIT_ID
git -C ../project-hotfix rev-parse --verify HEAD
git -C ../project-hotfix status --short --branch
git -C ../project-hotfix log -1 --format=fullerBefore making the first edit, compare the reported HEAD with the resolved base. git log can show the starting commit's metadata for your review record. A matching ID establishes the checkout's starting revision; it doesn't establish that dependencies, configuration or running services match the released environment.
If creation is refused, inspect git worktree list and the error. You may have reused a path or branch already associated with another checkout. Choose a new name or return to the intended existing worktree. This workflow doesn't need a force option that overrides those checks.
The original feature edits remain in their checkout; they aren't automatically copied into the hotfix. If the fix needs an uncommitted change from there, review and transfer that change deliberately. Keep the hotfix small enough to explain against its approved base.
Record what the second directory does—and doesn't—own
Linked worktrees belong to one repository. You can inspect the common repository location from either checkout with the following command. The path options in rev-parse distinguish the common Git directory from worktree-specific locations.
git rev-parse --path-format=absolute --git-common-dir
git -C ../project-hotfix rev-parse --path-format=absolute --git-common-dirThat shared relationship matters for configuration too. Git's configuration reference describes the worktreeConfig extension and worktree-specific settings. Don't assume a repository-level configuration change affects only the directory your shell happens to be in. Review the configuration scope before changing shared settings.
Your application needs a separate ownership check. Two checkouts can still connect to the same database or start processes using the same port. Before running tests or migrations, record the hotfix's configuration source, database target, service ports and background-worker behavior. Create disposable test resources where the exercise requires them. Copying production credentials into a second directory isn't a staging plan.
If your task is instead about downloading fewer objects or selecting fewer paths, see Krova's sparse checkout versus partial clone guide. A linked checkout answers a different question. If a dev container hosts either directory, the workspace-mount guide helps identify which machine or volume actually holds it.
Finish the fix without losing the workspace trail
Use the repository's documented build and test procedure in the prepared hotfix environment. Record the tested commit and result, then send the change through the normal review and release process. These are proposed steps, not tests performed for this article.
When the linked checkout is no longer needed, stop its running services and preserve any local data you still need. Check its status, including ignored files, before removing it. After your commits and other work are safely retained, use the normal worktree removal command from the original repository.
git -C ../project-hotfix status --short --untracked-files=all --ignored
# Only after preserving needed work and stopping this checkout's services:
git worktree remove ../project-hotfixFor the imagined developer, the useful handoff is short: approved base ID, hotfix branch and path, test-resource ownership, and the commit proposed for release. Return to the feature checkout and inspect its state before continuing. Your next action is to identify the real fix baseline; creating the extra directory comes after that decision.
Set up a remote development workspace on Cube
Krova Cube provides a self-managed Linux environment for your tools and development workflows. Plan source recovery and application test resources alongside the checkout.
Creation context: this AI-assisted guide uses a hypothetical feature and hotfix workflow. Commands were checked against the linked primary documentation but were not executed against an application repository. No personal testing by the bylined author is claimed. The cover is a generated conceptual illustration.




