Git pull requests and worktree

git-pr-worktree.md

Managing PRs with Git Worktrees

Using Git worktrees is an excellent way to review or test a Pull Request (PR) in a completely separate directory without messing up your current working branch or stash.

Here is a systematic procedure to fetch a remote PR, check it out into a dedicated worktree, and keep it updated.

Step 1: Initial Repository Setup (Run Once)

Using Git Worktree ensures you have everything under one roof. However, this is not a hard requirement. If you prefer just a regular repo directory, this is also possible.

1. Create the root directory

   Create and enter the top-level directory that will house your setup:

   mkdir project
   cd project

2. Clone the remote as a bare repository

   Clone your repository using the --bare flag into a hidden folder. A bare repository contains only the Git tracking database without an active working directory:

   git clone --bare git@github.com:username/repo.git .bare

3. Establish the Git storage link

   Create a special .git file at the root level that explicitly points future worktrees to your hidden bare directory:

   echo "gitdir: .bare" > .git

4. Configure GitHub PR tracking

   Inject the automated mapping configuration into your bare Git config file so that GitHub PR references are fetched natively as local remote-tracking branches. Then, perform your initial synchronization:

   git config --file .bare/config --add remote.origin.fetch "+refs/pull/*/head:refs/remotes/origin/pr/*"
   git fetch origin

5. Initialize the main branch worktree

   Create your primary working environment (main/) as your first official worktree tracking your default branch:

   git worktree add main main

Verify the file layout:

project/
├── .git               # Core configuration link
├── .bare/             # Hidden Git database tracking objects
└── main/              # Your primary working branch directory

Step 2: Create the Worktree

From the root project/ directory, create a dedicated folder to safely review a specific pull request without altering your main codebase:

git worktree add pr-42 -b pr-42 origin/pr/42

• What this does: It creates a new local branch (pr-42) that explicitly tracks origin/pr/42 and checks it out into your new worktree directory.

If you get a error message that the branch exists already, try this command:

git worktree add pr-42 pr-42

Step 3: Updating the Worktree with New Changes

If the PR author pushes new commits to their pull request, you will need to pull those updates into your worktree.

1. Navigate into your worktree directory.

2. Pull the changes:

   git pull

   Because the PR reference on GitHub can be force-pushed or rebased by the author, if a standard git pull fails due to a non-fast-forward update, you can safely run:

   git fetch origin && git reset --hard origin/pr/PR_NUMBER

   Be aware git reset --hard will immediately discard any uncommitted edits or experimental tweaks you made inside that specific worktree directory.

Step 4: Post-Review Clean-Up

When your testing or review concludes, return to your root repository structure to safely dismantle the environment and keep your disk space clean:

cd /path/to/project
git worktree remove pr-42
git branch -D pr-42