Manage Multiple Git Branches Easily with Worktrees

Master Git Worktrees for Efficient Branch Management

This tutorial will guide you through the process of setting up and utilizing Git worktrees to manage multiple branches simultaneously without the need for stashing or premature commits. You will learn how to create separate working directories for different branches, switch between them seamlessly, and maintain an organized project structure.

Prerequisites

• A basic understanding of Git commands (clone, add, commit, push, pull, status).
• A local Git repository that has been cloned as a bare repository into a .git folder within your project directory.

Step 1: Initialize Your Project with a Bare Repository

Before diving into worktrees, ensure your project is set up with a bare Git repository. This typically involves cloning a remote repository into a .git folder within your project’s root directory. Navigate to your project folder in the terminal. For example, if your project is named portfolio, you would be in the portfolio directory, and you should see a .git folder.

Example Command:

ls -a

This command should list the .git directory, confirming your bare repository setup. At this stage, there won’t be any project code files directly in the root, as Git has not created a default worktree.

Step 2: Create a Worktree for the Main Branch (Reference)

The first worktree we’ll create is for the main branch. This serves as a reference point and a place to pull the latest changes without disrupting your active development work. It will reside in its own dedicated directory.

1. Navigate to your project’s root directory (where the .git folder is located).
2. Execute the following Git command:

   git worktree add ../main main

   Note: The transcript suggests ./main. Using ../main assumes the .git folder is one level up from where you are running the command. If your .git folder is in the current directory, use ./main. For clarity and consistency with the transcript’s implied structure, we’ll use ./main assuming you are in the project root with the .git folder.

   git worktree add ./main main

3. Verify the creation by listing the directory contents:

   ls

   You should now see a main directory.

4. Change into the new directory and list its contents:

   cd main

   ls

   You will see your project files here, representing the current state of the main branch.

Expert Tip: This main worktree is primarily for viewing the latest code or pulling updates. Avoid making direct commits or significant changes here if you intend to keep it as a clean reference.

Step 3: Create a Worktree for a New Feature

Now, let’s create a dedicated worktree for developing a new feature. This worktree will have its own branch checked out.

1. Return to your project’s root directory:

   cd ..

2. Execute the git worktree add command, specifying the -b flag to create and check out a new branch, followed by the branch name and the path for the new worktree:

   git worktree add -b feature-abc ./feature-abc

   Here, feature-abc is both the new branch name and the directory name for this worktree.

3. List the directory contents to confirm:

   ls

   You should now see both the main and feature-abc directories.

4. Change into the new feature directory:

   cd feature-abc

5. Verify that you are on the correct branch:

   git status

   The output should indicate that you are on the feature-abc branch.

You can now start making changes, writing code, and committing directly within this feature-abc worktree without affecting your main branch or other worktrees.

Step 4: Create a Worktree for a Hotfix

When an urgent bug needs fixing, you can quickly create another worktree for a hotfix branch.

1. Ensure you are in your project’s root directory. While not strictly necessary, it’s good practice to manage worktree creation from the project root to avoid confusion.

   cd ..

2. Create the hotfix worktree and branch:

   git worktree add -b hotfix-123 ./hotfix-123

   This command creates a new directory named hotfix-123 and checks out a new branch called hotfix-123 within it.

3. List your worktrees to see all active directories:

   git worktree list

   This command will display all your worktrees, including main, feature-abc, and hotfix-123, along with their respective paths and current branches.

4. Navigate into the hotfix directory:

   cd hotfix-123

5. Make the necessary changes to fix the bug. For example, edit a file like readme.md.

   # Make your changes here
   # For example, edit readme.md
   

6. Stage, commit, and push the changes:

   git add .

   git commit -m "Update readme for hotfix"

   git push origin hotfix-123

Warning: Be mindful of which directory you are in when running Git commands. Each worktree operates independently with its own checked-out branch.

Step 5: Merge the Hotfix and Clean Up

Once the hotfix is deployed and merged into the main branch on your remote repository, you can remove the local hotfix worktree.

1. Navigate back to your project’s root directory:

   cd ..

2. Remove the hotfix worktree using the git worktree remove command:

   git worktree remove ./hotfix-123

   This command deletes the worktree directory and removes its entry from Git’s configuration.

3. Update your main worktree with the latest changes from the remote repository. Navigate to the main worktree:

   cd main

4. Pull the latest changes:

   git pull

   Alternatively, you could run git fetch in the root directory and then switch to the main worktree to pull.

You can now return to your feature development in the feature-abc worktree, knowing that your main branch is up-to-date.

Conclusion

Using Git worktrees allows you to maintain multiple branches checked out in separate directories, making it incredibly convenient to switch contexts between features, bug fixes, and main development without the overhead of stashing or frequent commits. This approach enhances organization and streamlines your development workflow.

Source: Git Worktrees Tutorial #4 – Worktree- First Approach (YouTube)