How to Use git worktree in Linux Terminal to Work on Multiple Branches Simultaneously

In software development workflows, developers frequently encounter interruptions: an urgent hotfix must be deployed to production while a feature branch is mid-refactoring, or a teammate requests an immediate code review on an active pull request. Traditionally, switching contexts requires stashing uncommitted local modifications (git stash), checking out the secondary branch, performing the task, returning to the original branch, and reapplying the stash. Alternatively, developers clone the entire repository into a separate directory, consuming double the disk space and duplicating network transfer overhead.

Git offers a far superior, built-in mechanism designed specifically for multi-branch concurrent development: git worktree. The git worktree command allows a single Git repository to maintain multiple linked working directories across different filesystem paths. Each worktree is checked out to its own independent branch, enabling you to build, test, and commit changes simultaneously without disturbing your primary working directory or stashing uncommitted work.

How Git Worktrees Differ from Multiple Clones

Understanding the architectural difference between a secondary clone and a linked worktree explains why worktrees are vastly more efficient:

• Shared Object Database: In a standard clone, Git maintains a separate .git database containing full commit histories, packfiles, and tree objects. A linked worktree shares the primary repository’s single .git database. It consumes virtually zero additional disk space beyond the actual working files checked out.
• Instant Local Branch Availability: Creating a worktree is instantaneous because no network transfer or local object copying occurs. All local branches, remote-tracking branches, and tags are accessible immediately.
• Unified Stash and Reflog: Because the underlying metadata is unified, operations performed in one worktree are immediately visible to the master repository.

Basic Syntax and Creating Your First Worktree

To inspect your current repository and view active worktrees, open your Linux terminal, navigate to your repository, and execute:

git worktree list

By default, Git displays a single entry pointing to the primary repository directory and its current checked-out branch:

/home/user/projects/web-app    a1b2c3d [main]

Adding a Worktree for an Existing Branch

To check out an existing branch into a dedicated working directory alongside your current project, specify the target directory path and the branch name:

git worktree add ../web-app-hotfix hotfix/v2.1.1

Git creates the directory ../web-app-hotfix, links it to the main repository’s database, and checks out the hotfix/v2.1.1 branch. You can now open a new terminal window or IDE session inside ../web-app-hotfix and run tests, modify files, and create commits independently.

Adding a Worktree and Creating a New Branch Simultaneously

If you want to start a completely new branch within a separate worktree, supply the -b flag followed by the new branch name:

git worktree add -b feature/auth-redesign ../web-app-auth main

This command branches off main, creates a new local branch named feature/auth-redesign, and sets up the working tree in ../web-app-auth.

Managing and Inspecting Linked Worktrees

To monitor your environment as project demands evolve, use these management commands:

Listing Active Worktrees

git worktree list

Output reflects all connected directories along with their checked-out branches:

/home/user/projects/web-app         a1b2c3d [main]
/home/user/projects/web-app-hotfix  8f9e0d1 [hotfix/v2.1.1]
/home/user/projects/web-app-auth    b4c5d6e [feature/auth-redesign]

Branch Locking and Safety Mechanisms

Git strictly prevents checking out the same branch in two different worktrees simultaneously. If you attempt to checkout a branch that is already active elsewhere, Git returns an explicit safety warning:

fatal: 'hotfix/v2.1.1' is already checked out at '/home/user/projects/web-app-hotfix'

This protection eliminates accidental branch divergence and conflicting index states.

Removing Worktrees and Cleaning Up Resources

Once your hotfix is merged or feature testing is complete, you should cleanly decommission the linked directory.

Standard Removal

To safely delete a worktree, run the remove command from within your primary repository:

git worktree remove ../web-app-hotfix

Git verifies that the worktree contains no untracked files or uncommitted changes, deletes the directory from the filesystem, and removes the administrative link in .git/worktrees/.

Force Removal

If the worktree contains generated build artefacts, logs, or uncommitted edits that you intentionally want to discard, pass the --force flag:

git worktree remove --force ../web-app-hotfix

Pruning Stale Worktree Metadata

If you manually deleted a worktree directory using standard Linux commands (such as rm -rf ../web-app-hotfix) without running git worktree remove, Git retains stale administrative records in its internal database. To clear these orphan references, execute:

git worktree prune

Integrating Worktrees into Real-World Development Workflows

Adopting git worktree transforms common multi-tasking bottlenecks:

• Long-Running Compilation Tasks: If building your project takes several minutes, you can run a build on your feature worktree while continuing active development in your primary tree.
• Pull Request Reviews: Instead of interrupting your flow to check out a colleague’s branch, spawn a temporary worktree in seconds (git worktree add ../review-pr123 pr/123), inspect and test the code, and remove it immediately after approval.
• Independent Environment Variables: Each linked worktree has its own dedicated directory root, allowing you to maintain distinct local .env files or build configurations for staging, production, and testing branches without overwriting credentials.

By leveraging git worktree directly from the Linux terminal, developers eliminate the cognitive friction of context switching and achieve seamless parallel development across complex codebases.