Add setup-sandbox-with-worktrees script for manual testing + warn on different final WD

Author: PawelLipski

docs/man/git-machete.1

@@ -27,9 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "GIT-MACHETE" "1" "Oct 09, 2025" "" "git-machete"
+.TH "GIT-MACHETE" "1" "Nov 11, 2025" "" "git-machete"
 .SH NAME
-git-machete \- git-machete 3.37.0
+git-machete \- git-machete 3.37.1
 .sp
 git machete is a robust tool that \fBsimplifies your git workflows\fP\&.
 .sp

git_machete/client/traverse.py

@@ -12,7 +12,7 @@
 from git_machete.git_operations import (GitContext, LocalBranchShortName,
                                         SyncToRemoteStatus)
 from git_machete.utils import (bold, flat_map, fmt, get_pretty_choices,
-                               get_right_arrow)
+                               get_right_arrow, warn)
 
 
 class TraverseReturnTo(ParsableEnum):
@@ -94,8 +94,7 @@ def _switch_to_branch_worktree(
             # Branch is checked out in a worktree
             # Only cd if we're in a different worktree
             if current_worktree_root != worktree_path:
-                print(f"Branch {bold(branch)} is checked out in worktree at {bold(worktree_path)}")
-                print("Changing directory to that worktree")
+                print(f"Changing directory to {bold(worktree_path)} worktree where {bold(branch)} is checked out")
                 os.chdir(worktree_path)
                 # Flush root dir cache after directory change so get_root_dir() returns the correct path
                 self._git.flush_root_dir_cache()
@@ -143,6 +142,7 @@ def traverse(
         # Store the main worktree path and initial directory for later restoration
         main_worktree_path = self._git.get_main_worktree_path()
         initial_branch = nearest_remaining_branch = self._git.get_current_branch()
+        initial_worktree_root = self._git.get_root_dir()
 
         # Fetch worktrees once at the start to avoid repeated git worktree list calls
         self.__worktrees_cache: Dict[LocalBranchShortName, str] = self._git.get_worktrees()
@@ -500,3 +500,13 @@ def traverse(
             print(
                 f"The initial branch {bold(initial_branch)} has been slid out. "
                 f"Returned to nearest remaining managed branch {bold(nearest_remaining_branch)}")
+
+        # Warn if the initial directory doesn't correspond to the final checked out branch's worktree
+        final_branch = self._git.get_current_branch()
+        final_worktree_path = self.__worktrees_cache.get(final_branch)
+        if final_worktree_path and initial_worktree_root != final_worktree_path:
+            # Final branch is checked out in a worktree different from where we started
+            warn(
+                f"Note: branch {bold(final_branch)} is checked out in worktree at {bold(final_worktree_path)}.\n"
+                f"You may want to change directory with:\n"
+                f"  `cd {final_worktree_path}`")

graphics/setup-sandbox-with-worktrees

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+
+set -e -o pipefail -u
+
+root_dir=$(realpath "${1-$HOME}")
+
+# First, set up the regular sandbox
+script_dir=$(cd "$(dirname "$0")" && pwd)
+"$script_dir/setup-sandbox" "$root_dir"
+
+# Now create worktrees
+cd "$root_dir/machete-sandbox"
+
+echo
+echo "Creating worktrees..."
+echo
+
+# Create worktrees for some branches
+git worktree add "$root_dir/machete-sandbox-worktrees/allow-ownership-link" allow-ownership-link
+echo "Created worktree for allow-ownership-link at $root_dir/machete-sandbox-worktrees/allow-ownership-link"
+
+git worktree add "$root_dir/machete-sandbox-worktrees/build-chain" build-chain
+echo "Created worktree for build-chain at $root_dir/machete-sandbox-worktrees/build-chain"
+
+git worktree add "$root_dir/machete-sandbox-worktrees/master" master
+echo "Created worktree for master at $root_dir/machete-sandbox-worktrees/master"
+
+# Create a worktree with detached HEAD at the tip of call-ws
+call_ws_sha=$(git rev-parse call-ws)
+git worktree add --detach "$root_dir/machete-sandbox-worktrees/detached-call-ws" "$call_ws_sha"
+echo "Created worktree with detached HEAD at $root_dir/machete-sandbox-worktrees/detached-call-ws (commit $call_ws_sha from call-ws)"
+
+# Create another worktree with detached HEAD at the tip of hotfix/add-trigger
+hotfix_sha=$(git rev-parse hotfix/add-trigger)
+git worktree add --detach "$root_dir/machete-sandbox-worktrees/detached-hotfix" "$hotfix_sha"
+echo "Created worktree with detached HEAD at $root_dir/machete-sandbox-worktrees/detached-hotfix (commit $hotfix_sha from hotfix/add-trigger)"
+
+echo
+echo "Worktree list:"
+git worktree list
+echo
+echo
+git machete status
+echo
+echo

tests/test_traverse.py

@@ -1974,10 +1974,9 @@ def test_traverse_with_worktrees(self) -> None:
 
         # Verify key behaviors happened:
         # 1. It switched to feature-1 worktree
-        assert "Branch feature-1 is checked out in worktree at" in output
-        assert "Changing directory to that worktree" in output
+        assert "worktree where feature-1 is checked out" in output
         # 2. It switched to feature-2 worktree
-        assert "Branch feature-2 is checked out in worktree at" in output
+        assert "worktree where feature-2 is checked out" in output
         # 3. Operations were performed
         assert "Rebasing feature-1 onto develop" in output
         assert "Rebasing feature-2 onto feature-1" in output
@@ -2094,3 +2093,74 @@ def test_traverse_updates_worktree_cache_on_checkout(self) -> None:
         # Verify branch-2 was checked out and pushed
         assert "Checking out branch-2" in output
         assert "Pushing untracked branch branch-2" in output
+
+    def test_traverse_warns_when_final_branch_in_different_worktree(self) -> None:
+        if get_git_version() < (2, 5):
+            return
+
+        create_repo_with_remote()
+        new_branch("root")
+        commit("root")
+        push()
+        new_branch("branch-1")
+        commit("branch-1")
+        push()
+        new_branch("branch-2")
+        commit("branch-2")
+        push()
+
+        body: str = \
+            """
+            root
+                branch-1
+                    branch-2
+            """
+        rewrite_branch_layout_file(body)
+
+        # Create a worktree for branch-2
+        check_out("root")
+        branch_2_worktree = add_worktree("branch-2")
+
+        # Make root have an additional commit so branch-1 needs rebase
+        check_out("root")
+        commit("root additional commit")
+        push()
+
+        # Start from root (main worktree), traverse should process through branch-2
+        check_out("root")
+        output = launch_command("traverse", "-y")
+
+        # Verify the warning is emitted
+        assert "Note: branch branch-2 is checked out in worktree at" in output
+        assert f"You may want to change directory with:\n  cd {os.path.realpath(branch_2_worktree)}" in output
+
+    def test_traverse_no_warn_when_final_branch_in_same_worktree(self) -> None:
+        if get_git_version() < (2, 5):
+            return
+
+        create_repo_with_remote()
+        new_branch("root")
+        commit("root")
+        push()
+        new_branch("branch-1")
+        commit("branch-1")
+        push()
+
+        body: str = \
+            """
+            root
+                branch-1
+            """
+        rewrite_branch_layout_file(body)
+
+        # Create a worktree for branch-1
+        check_out("root")
+        add_worktree("branch-1")
+
+        # Start from root (main worktree), traverse ends on root (same worktree)
+        check_out("root")
+        output = launch_command("traverse", "-y", "--return-to=here")
+
+        # Verify the warning is NOT emitted
+        assert "Note: branch" not in output
+        assert "You may want to change directory with:" not in output