More worktree commands

Time to read:	Activity duration:
10 minutes	15 minutes

Now that you are comfortable with the core add, list, remove and prune worktree actions, you should be at ease for most workflows.

But you can also progress to the next level if you learn some extra capabilities of worktrees, and that's what we'll check in this section.

Worktree provide some extra sub-commands to handle few specific use cases:

• move
• lock and unlock
• repair

Overview

Moving a worktree

git worktree move {SOURCE_FOLDER} {DESTINATION_FOLDER}

The move subcommand for git worktree will move a worktree folder to a new location:

• {SOURCE_FOLDER} is the original worktree folder.
• {DESTINATION_FOLDER} is the new path for the worktree

Lock and unlock worktrees

git worktree lock [ --reason {REASON} ] {FOLDER}
git worktree unlock {FOLDER}

The lock sub-command ensure that a specific worktree cannot be updated. The opposite unlock sub-command allow again modifications.

• {FOLDER} is the worktree folder to lock or unlock;
• {REASON} is an optional text message to attach to a locked worktree to explain why it was locked.

Repairing worktrees

git worktree repair {PATH} ...

The repair sub-command will attempt to repair a workspace located on the specified paths.

• {PATH} values are one, or more, path to check for workspace to be repaired.

Setup activity

Call the helper script to create the wt_more activity:

Command

./scripts/create-playground.sh wt_more

Result

[INFO] Starting activity builder for 'wt_more'
[INFO] Created activity folder: /Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more
Cloning into 'nanorpm_main'...
remote: Enumerating objects: 252, done.
remote: Total 252 (delta 0), reused 0 (delta 0), pack-reused 252 (from 1)
Receiving objects: 100% (252/252), 497.60 KiB | 3.27 MiB/s, done.
Resolving deltas: 100% (147/147), done.
[Step] Cloned repository https://gitlab.com/sgamel-projects/nanorpn.git
Already on 'main'
Your branch is up to date with 'origin/main'.
Preparing worktree (checking out 'feature-a')
HEAD is now at 4188ec5 Test: add comprehensive integration tests for application workflow
Preparing worktree (checking out 'feature-b')
HEAD is now at 4188ec5 Test: add comprehensive integration tests for application workflow
Preparing worktree (checking out 'feature-c')
HEAD is now at 4188ec5 Test: add comprehensive integration tests for application workflow
Preparing worktree (checking out 'feature-d')
HEAD is now at 4188ec5 Test: add comprehensive integration tests for application workflow
[INFO] Successfully built activity 'wt_more' in /Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more
[INFO] You can now navigate to /Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more to work on the activity.

cd /Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more

Your playground folder wt_more will contain 4 subfolders.

One extra worktree folder were created inside the nanorpm_main clone. An unexpected location.

Moving a worktree

Go the the main clone folder and check the list of worktrees:

cd playgrounds/wt_more/nanorpm_main
git worktree list

The result will show that one worktree is located inside the nanorpm_main folder:

/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_main                    4188ec5 [main]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-a               4188ec5 [feature-a]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-b               4188ec5 [feature-b]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-c               4188ec5 [feature-c]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_main/nanorpm_feature-d  4188ec5 [feature-d]

This is typically something that can be done because of a manual error when creating the worktree.

Let's be consistent and move this worktree into the parent folder, so they are all siblings:

git worktree move ./nanorpm_feature-d ..

And check the result:

/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_main       4188ec5 [main]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-a  4188ec5 [feature-a]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-b  4188ec5 [feature-b]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-c  4188ec5 [feature-c]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-d  4188ec5 [feature-d]

That's fixed. All worktrees are stored in the same location.

Locking worktrees

You should not have to manually lock or unlock your worktrees.

But this might be useful if you need to prevent a worktree to be impacted by a global operation, like a merge or rebase.

This is also a good way to ensure a worktree won't be deleted by a git worktree prune command if the worktree is located on network location or removable storage.

Lets start by locking the nanorpm_feature-a worktree and see what can be the impact.

git worktree lock ../nanorpm_feature-a

If you list again the worktree you will see the locked mention is now displayed:

/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_main       4188ec5 [main]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-a  4188ec5 [feature-a] locked
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-b  4188ec5 [feature-b]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-c  4188ec5 [feature-c]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-d  4188ec5 [feature-d]

Now go to the nanorpm_feature-a folder and edit the package.json file. Just change version number and save.

Changes

diff --git a/package.json b/package.json
index 5315707..95c3d7c 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "nanoRPN",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "A terminal-based RPN calculator",
   "main": "dist/main.js",
   "type": "module",

Command

git diff

Let's stage and commit this change:

git add package.json
git commit -m 'test lock wt'

Remark

Worktree is locked, but this do not prevent you to stage files and commit them!

Let simulate a removable storage.

• Go to wt_morefolder;
• Change the name nanorpm_feature-a to nanorpm_moved;
• Go back to the nanorpm_main folder and display the list of worktrees.

Commands

cd ..
mv nanorpm_feature-a nanorpm_moved
cd nanorpm_main
git worktree list

Result

/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_main       4188ec5 [main]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-a  bd986c2 [feature-a] locked
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-b  4188ec5 [feature-b]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-c  4188ec5 [feature-c]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-d  4188ec5 [feature-d]

Compared to our previous renaming of the worktree folder in remove section, you can remark that:

• folder still appear in previous path as locked;
• folder is not flagged as prunable.

What will happens if we unlock the worktree now?

git worktree unlock ../nanorpm_feature-a

If you check again the worktree status, you will notice that as folder no longer appears as locked, it is now flagged as prunable and will be removed if you run the git worktree prune command.

Fixing a manual rename

There's multiple ways to come back to a safe place and link again the nanorpm_moved to our local repository as a worktree.

• manually revert the rename;
• or use the repair feature. :::

Repairing

We still have the nanorpm_moved folder not attached to our repository. And nanorpm_feature-a is missing.

Let's repair this:

bash

git worktree repair ../nanorpm_moved

Result

repair: gitdir absolute/relative path mismatch: /Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_main/.git/worktrees/nanorpm_feature-a/gitdir
repair: .git file absolute/relative path mismatch: /Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-c
repair: .git file absolute/relative path mismatch: /Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-d
repair: .git file absolute/relative path mismatch: /Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-b
repair: .git file absolute/relative path mismatch: /Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_moved

If you check now the list of worktrees you will get an output similar to the following:

/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_main       4188ec5 [main]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-b  4188ec5 [feature-b]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-c  4188ec5 [feature-c]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_feature-d  4188ec5 [feature-d]
/Users/sylvain/dev/lab/git-tutorials/playgrounds/wt_more/nanorpm_moved      bd986c2 [feature-a]

Our repository is now fixed. Branch feature-a is now attached to the expected folder nanorpm_moved and nanorpm_feature-ais no longer listed as a worktree.