Working with PairSpaces

PairSpaces makes the way you work easier to work with people. You can work alone in a secure development environment and share with others when you feel like it. You can pair from the same Space with a team member sitting beside you or sitting on the other side of the world. And you can share your results with stakeholders from your Space.

Whatever way you work today, PairSpaces makes it easier for you to work together with your team when you want to.

PairSpaces does something special, however. It makes it particularly easy to work in parallel from the same Space. This means you and your team can work independently and share code from branches when you want to work together.

PairSpaces does this using a feature of Git called worktrees. PairSpaces and worktrees make it faster and cheaper for you to produce better software than ever before.

What are Worktrees?

A Git worktree is a feature that creates multiple working directories, called worktrees, from a single Git repository. Each worktree is an independent checkout of a commit (usually a branch), which means you can work on different branches by simply changing directory.

Worktrees were introduced to Git in 2015 to solve the problem of working on multiple branches simultaneously. Before worktrees, Git users used stashes or were forced to commit uncommitted changes prior to switching branches. A long list of stashes and forced commits made it difficult to keep track of the state of each branch. Worktrees are independent checkouts of a commit and you can switch between checkouts by changing directory, but there is more to them than just that.

Worktrees in Detail

When you create a worktree, Git sets up a new working directory that represents a specific branch or commit, but the metadata and objects (commits, trees, blobs, etc.) are still stored in the original repository’s .git directory.

The main repository or primary worktree contains the .git directory with the complete repository metadata - the index and all objects and refs.

Each additional worktree has its own working directory with a checked-out branch or commit. The working directory includes a gitdir file in its .git folder that points to the main repository’s .git directory and a separate HEAD file pointing to its current branch or commit. Additional worktrees do not have a separate object database; worktrees share the object database of the main repository.

Worktrees do create overhead when managing multiple copies of a repository, however, for most teams using worktrees this is not significant.

Changes

Changes in a worktree are tracked the same way as in a standard Git repository. Each worktree has its own working directory, so any file changes (new, modified, or deleted files) are local to that worktree. Each worktree has its own staging area (index) for staging changes. This ensures that staging changes in one worktree doesn’t affect others. Commits made in a worktree are tracked and stored in the shared object database. However, they update the branch or commit associated with that specific worktree.

Unstaged and staged changes are tracked only in the worktree in which they occur. Committed changes are stored in the shared object database, making them available to other worktrees that checkout the same branch or commit.

Worktrees in Action

To understand how to use worktrees, let's work with a new repository.

Set up a Git Repository

> mkdir primary
> cd primary
> git init
Initialized empty Git repository in /home/ec2-user/primary/.git/
> git branch -M main

Now create a file.

> echo "Working together is the default." > file.txt
> git add file.txt
> git commit -m "feat: initial commit"
[main (root-commit) ed80051] feat: initial commit
 1 file changed, 1 insertion(+)
 create mode 100644 file.txt

Create a Worktree for a Feature Branch

Create a new branch and a corresponding worktree to work on a feature.

> git branch feat/content
> git worktree add -b feat/content ../worktrees/feature
Preparing worktree (new branch 'feat/content')
HEAD is now at ed80051 feat: initial commit

Make Changes in the Feature Worktree

Navigate to the worktree and make some changes.

> cd ../worktrees/feature
> echo "So change the world together." >> file.txt
> git add file.txt
> git commit -m "feat: added feature branch content"
[feat/content 3c7255d] feat: added feature branch content
 1 file changed, 1 insertion(+)

Now, file.txt in the feature branch feat/content contains two lines.

Working together is the default.
So change the world together.

Switch Back to the Main Worktree

Navigate back to the main worktree to continue work on the main branch.

> cd ../../primary

Check the contents of file.txt.

> cat file.txt

Working together is the default.

Review Changes Between Branches

Use git diff to review changes between the main and feature branches.

> git diff main feat/content
diff --git a/file.txt b/file.txt
index 12ad575..33c99f4 100644
--- a/file.txt
+++ b/file.txt
@@ -1 +1,2 @@
 Working together is the default.
+So change the world together.

This will show the differences between the two branches.

Test the Merge in a Temporary Worktree

To test merging the feature branch into main, create a temporary worktree.

> git worktree add ../worktrees/temporary main -b test/content
Preparing worktree (new branch 'test/content')
HEAD is now at ed80051 feat: initial commit
> cd ../worktrees/temporary
> git merge feat/content
Updating ed80051..3c7255d
Fast-forward
 file.txt | 1 +
 1 file changed, 1 insertion(+)

If the merge is successful, you can view file.txt to see the combined content.

> cat file.txt

Working together is the default.
So change the world together.

Finalize the Merge

Once satisfied with the changes, return to the main worktree and merge the feat/content branch.

> cd ../../primary
> git merge feat/content
Updating ed80051..3c7255d
Fast-forward
 file.txt | 1 +
 1 file changed, 1 insertion(+)

Clean Up Worktrees

Remove the temporary worktree.

> git worktree remove ../worktrees/temporary
> git branch -D test/content
Deleted branch test/content (was 3c7255d).
> git worktree remove ../worktrees/feature
> git branch -D feat/content
Deleted branch feat/content (was 3c7255d).

Learn More About Worktrees

We recommend reviewing the documentation on Git worktrees using the online version of the Pro Git book.

Working Together in Spaces

Git worktrees make working together possible in a new and exciting way. They allow you and your team to work together from the same machine, in the same repository, but from different branches. You can review each other's code using diffs and merge after receiving feedback.

The thing you need to do first, however, is to share your machine with someone. And that involves all sorts of security concerns, for example, creating and distributing keys, creating secure network access, and monitoring that network. It's a lot of work.

That's where PairSpaces comes in. PairSpaces does all of this for you, so that you can work together and change the world. Learn how to use PairSpaces to work together next.