Git Worktrees In Use
Tags: git
Published: 2022-12-09 07:07:32

---
title: Git Worktrees In Use
published: true
date: 2022-05-18 00:00:00 UTC
tags: git
canonical_url: https://www.prestonlamb.com/blog/git-worktrees-in-use
---

## [tldr;](#tldr)

Most of us use Git every day, but generally use only the features that we are familiar with and allow us to do our job. There's nothing wrong with this at all, but learning new tricks can take your productivity up a level! With that in mind, let me introduce you to Git Worktrees.

Git Worktrees allow you to pull a git repository to your computer and then work on multiple branches at a time if desired. A standard `git clone` command pulls the repository to your machine and starts you working on a particular branch. If you need to switch branches, you have to either commit and push your code or stash the changes. When you clone the repo with the intent to use worktrees, you don't check out a particular branch initially. Let's learn how to use Git Worktrees!

## [Cloning Your Repo](#cloning-your-repo)

Let's start by cloning the repository to your machine.

```sh
$ git clone --bare git@github.com:pjlamb12/worktree-demo.git worktree-demo
```

The above command looks similar to your normal `git clone`, with one important extra piece: `--bare`. This flag is what clones the repo to your machine without checking out a particular branch. You can read more about the flag [here](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---bare). The last part of the command, `worktree-demo`, names the folder that the repository will be cloned into. Normally `git clone` will clone the repo into a folder that's named the same as the repository URL, minus the `.git`. `git clone --bare` will keep the `.git` extension on the folder when cloning. If you don't want the `.git` on the folder name, provide the name of the folder as I've done above.

At this point, you have the repository cloned to your machine. If you change into the directory and list the contents, you'll see a few files like `HEAD`, `config`, and `description`, along with a couple folders like `hooks`, `info`, and `objects`. This is just an example; yours may not be exactly the same.

If you run the `git status` command, you'll see an error that says something along the lines of, "this operation must be run in a work tree". This lets you know that you can't do any work on your repository in this main folder. Let's look next at how to create a worktree so you can make some changes to your app.

## [Adding a Worktree](#adding-a-worktree)

Let's add our first worktree, which we'll call `main` and will be based off the `HEAD` of the repo. You can add that worktree like this:

```sh
$ git worktree add main
```

If you list the contents of the directory, you'll now see a new folder called `main`. If you change into that directory and list the contents you'll see your application code. Also, `git status` will now give you the status that you expect to see. You'll no longer see the error mentioned above.

You can now always view the code in your repository at the `main` branch. To update the worktree, run the `git pull` command. This will get all the latest commits to the branch and update your worktree. I recommend not doing any work on your application in this worktree, however. This worktree is useful to have on your computer and ready to go so that you can troubleshoot any issues that teammates may be having, for example. If you want to make a change to the application, create a new worktree just like you would create a new branch.

### [Adding a Worktree with a New Branch](#adding-a-worktree-with-a-new-branch)

The command to create a new worktree and a new branch is similar to the `add` command above, but with an extra flag.

```sh
$ git worktree add -b my-new-branch worktree-name
```

The flag you need to provide is the `-b branch-name` flag. Whatever you use as the value for this flag will be the name of the branch when you push it to the repository. The last argument, `worktree-name`, is the name of the worktree on your computer and will be the name of the folder where the code is stored. This command does the same thing as the first `add` command, but a new branch is created with the given name.

Now that you have a worktree and branch created to make your changes, you can work on your application the same as you always do. Make changes, commit them, push them, and then merge the pull request. The first time you push the code, remember to use the `--set-upstream` flag:

```sh
$ git push --set-upstream origin my-new-branch
```

After you've used this flag the first time, `git push` will suffice.

### [Add a Worktree Based on a Remote Branch](#add-a-worktree-based-on-a-remote-branch)

The above commands are helpful but don't cover all situations. Sometimes you need to help your coworker with an issue they are seeing on their branch. This is where you can really see the benefits of worktrees. You can leave the worktree that you're working on untouched on your machine, and add a new worktree based on your coworker's branch. You can add this new worktree like this:

```sh
$ git worktree add worktree-name branch-name
```

Again, this is similar to the first `add` command but the `branch-name` argument will start you off on a branch in the repository instead of from the `HEAD` commit. You'll be able to change into the worktree folder and browse the code as your coworker is seeing it, but you won't have been required to commit your unfinished code to switch branches.

## [Updating a Worktree](#updating-a-worktree)

Often when you're working on a feature branch the main branch has someone else's code merged to it. At that point you'll need to update your feature branch with `rebase` or `merge`. These same methods of updating your worktree can be used. You can update your worktree by rebasing or merging. You can decide the which method you would like to use. [This article](https://betterprogramming.pub/differences-between-git-merge-and-rebase-and-why-you-should-care-ae41d96237b6) explains the differences between `rebase` and `merge`.

Before merging or rebasing, make sure that your local `main` worktree has been updated with `git pull`. After your local worktree is updated, you can `merge` or `rebase` your feature branch.

## [Removing a Worktree](#removing-a-worktree)

After you finish up with a worktree, you'll want to remove the worktree from your machine. Each worktree will take up space on your hard drive, so you'll eventually run out room if you don't remove unused workspaces. You can remove them with the `remove` command:

```sh
$ git worktree remove worktree-name
```

The worktree and all related files will be removed from your computer.

## [Listing Worktrees](#listing-worktrees)

If you need to list the worktrees you've created, you can use the `list` command:

```sh
$ git worktree list
```

This will list all the local worktrees you've created on your machine.

## [Conclusion](#conclusion)

When I found out about worktrees, I could see the potential benefits immediately. The ability to have multiple branches checked out on your computer at a single time is really powerful, especially when working with a team. Gone are the days of committing completely unfinished code to your feature branch so you can switch branches to help a coworker. It's not necessarily a "one size fits all" solution, but I'm excited about the possibilities. Hopefully this article helps you get started