3, 4, 5, or more

PairSpaces recommends Git worktrees as a way to collaborate with your team from your Space. This page describes the advantages and disadvantages of using Git worktrees to work together.

Git Worktrees are Lightweight Copies of Your Work

Git worktrees are lightweight copies of your repository - think of them as a copy of your repository, but one that shares .git/ with the main worktree. This is good news when you want to collaborate with three, four, or more people from your Space, but it gets better.

Worktrees make it easy to compare differences - diffs - across branches. It's as easy as running git diff branch_name, whether that branch is a conventional branch or a worktree.

And because you're working together from a Space, you don't have any delay in reviewing each other's code. This faster collaboration is possible, because you don't use remotes, don't have PR queues, and you avoid context switching.

And importantly, Git worktrees are native to Git. PairSpaces isn't adding anything to a workflow you don't already have elsewhere.

Git Worktrees are Local Copies of Your Work

When you create a worktree, a local copy of your repository is created (but not a copy of the .git/ index). Because a worktree is a local copy of your repository, there will be a limit on the number of open files the underlying filesystem supports. If each collaborator runs a full development environment, for example, running a FastAPI server or virtualenv, you may hit filesystem or memory limitations. This will likely put an upper limit on how the number of collaborators you can work with at once of between 5 and 10 users, however, this will depend on your own use case.

Another sitaution to be aware of is merge conflcits. If users in two different worktrees make changes to the same file, you will still encounter merge conflicts just as you would if someone attempted to merge a file from a remote repository with a copy of that file on their local machine. Nothing different from your normal workflow, but worth pointing out.

Working Together using Worktrees

And that's about it! You benefit from faster feedback, iteration, and collaboration with zero context-switching. The key drawback is if your code requires a lot of filesystem or memory resources. In this case, PairSpaces has a range of CPU/RAM options to choose from when creating your Space.

One more thing, however. When you work together with your team, how does each person get recognition for their contribution? The answer is to use Git! Let's see an example.

Being Recognized for Your Work

To understand how to record your work as your work, let's remember how Git checks for user identity. First, it looks at the per-repository or per-worktree level:

.git/config

Then it looks at its global configuration:

~/.gitconfig

And finally it looks at its system-wide configuration (this isn't common, however):

/etc/gitconfig

So, to record your contribution when working together, after you create your worktree...

> git worktree add ../worktrees/my-work -b feat/my-new-feature

...configure Git to use your name and identity:

> git config user.name "Alice" && git config user.email "alice@pairspaces.com"

And when your work is merged with your team you will see something like this:

> git log
commit fa1dd57c70393f344e86c933ff8447be28eb9c90 (HEAD -> merge)
Merge: 3ec9da2 b36290d
Author: Bob <bob@pairspaces.com>
Date:   Mon Apr 14 23:09:52 2025 +0000

    feat: merged bob comment

commit b36290d3451851828e6da78e5f9118ab0e6d5603 (review, feat/bob)
Author: Bob <bob@pairspaces.com>
Date:   Mon Apr 14 22:56:58 2025 +0000

    feat: bob added comment

commit 3ec9da2225e8ed901b56f25a06eeabe12569aac5 (feat/alice)
Author: Alice <alice@pairspaces.com>
Date:   Mon Apr 14 22:55:54 2025 +0000

    feat: alice added comment

commit 4a906dd043546bcd3823a6e41ea84bb7fa49fe71 (main)
Author: Carol <carol@pairspaces.com>
Date:   Mon Apr 14 22:54:06 2025 +0000

    feat: initial commit