Add cd-into-temporary-worktree value for machete.traverse.whenBranchNotCheckedOutInAnyWorktree git config key

Author: PawelLipski

RELEASE_NOTES.md

@@ -1,7 +1,8 @@
 # Release notes
 
-## New in git-machete 3.39.3
+## New in git-machete 3.40.0
 
+- added: `cd-into-temporary-worktree` value for `machete.traverse.whenBranchNotCheckedOutInAnyWorktree` git config key (suggested by @andrii0lomakin)
 - changed: when a branch is behind remote (needs a pull), `git machete traverse` now skips rebase,
   just as it did already when branch is diverged from & older than remote (suggested by @lsierant)
 - fixed: when `git machete traverse` failed on a rebase within a worktree,

docs/man/git-machete.1

@@ -28,9 +28,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" "Mar 30, 2026" "" "git-machete"
+.TH "GIT-MACHETE" "1" "Mar 31, 2026" "" "git-machete"
 .SH NAME
-git-machete \- git-machete 3.39.3
+git-machete \- git-machete 3.40.0
 .sp
 git machete is a robust tool that \fBsimplifies your git workflows\fP\&.
 .sp
@@ -494,13 +494,20 @@ The default value of this key is \fBtrue\fP\&.
 Configuration key value can be overridden by the presence of the \fB\-\-push\fP or \fB\-\-push\-untracked\fP flags.
 .TP
 .B \fBmachete.traverse.whenBranchNotCheckedOutInAnyWorktree\fP:
-Controls the behavior of \fBgit machete traverse\fP when checking out a branch that is not currently checked out in any worktree.
+Controls the behavior of \fBgit machete traverse\fP when it needs to act on a branch that is not currently checked out in any worktree.
 .sp
-The default value is \fBcd\-into\-main\-worktree\fP, which means that \fBtraverse\fP will change directory to the main worktree before checking out the branch.
-.sp
-Set to \fBstay\-in\-the\-current\-worktree\fP to make \fBtraverse\fP stay in whatever worktree has already been reached by that point,
-and check out the branch there instead.
-Note that this worktree might be different then the initial working directory where \fBtraverse\fP started.
+Allowed values:
+.INDENT 7.0
+.IP \(bu 2
+\fBcd\-into\-main\-worktree\fP (default): change directory to the main worktree and check out the branch there.
+.IP \(bu 2
+\fBstay\-in\-the\-current\-worktree\fP: check out the branch in whichever worktree \fBtraverse\fP is currently operating in,
+without changing directory. Note that this worktree might differ from the one where \fBtraverse\fP originally started.
+.IP \(bu 2
+\fBcd\-into\-temporary\-worktree\fP: create a new worktree in a temporary directory, check out the branch there,
+and remove this temporary worktree once \fBtraverse\fP moves on to the next branch (or finishes).
+This ensures that no existing (non\-temporary) worktree has its checked\-out branch changed by \fBtraverse\fP\&.
+.UNINDENT
 .TP
 .B \fBmachete.worktree.useTopLevelMacheteFile\fP:
 The default value of this key is \fBtrue\fP, which means that the path to branch layout file will be \fB\&.git/machete\fP
@@ -2062,7 +2069,7 @@ whether a gray edge is displayed in \fBstatus\fP,
 whether \fBtraverse\fP suggests to slide out the branch.
 .UNINDENT
 .TP
-.B \fBmachete.status.extraSpaceBeforeBranchName\fP
+.B \fBmachete.status.extraSpaceBeforeBranchName\fP:
 To make it easier to select branch name from the \fBstatus\fP output on certain terminals
 (like Alacritty \%<https://\:github\:.com/\:alacritty/\:alacritty>), you can add an extra space between └─ and branch name
 by setting \fBgit config machete.status.extraSpaceBeforeBranchName true\fP\&.
@@ -2303,19 +2310,26 @@ If set to \fBfalse\fP, this remote will not be fetched before the traversal.
 The default value of this key is \fBtrue\fP\&.
 This is useful for excluding remotes that are temporarily offline, or take a long time to respond.
 .TP
-.B \fBmachete.traverse.push\fP
+.B \fBmachete.traverse.push\fP:
 Set to \fBfalse\fP to change the behavior of \fBgit machete traverse\fP so that it doesn\(aqt push branches by default.
 The default value of this key is \fBtrue\fP\&.
 Configuration key value can be overridden by the presence of the \fB\-\-push\fP or \fB\-\-push\-untracked\fP flags.
 .TP
-.B \fBmachete.traverse.whenBranchNotCheckedOutInAnyWorktree\fP
-Controls the behavior of \fBgit machete traverse\fP when checking out a branch that is not currently checked out in any worktree.
-.sp
-The default value is \fBcd\-into\-main\-worktree\fP, which means that \fBtraverse\fP will change directory to the main worktree before checking out the branch.
+.B \fBmachete.traverse.whenBranchNotCheckedOutInAnyWorktree\fP:
+Controls the behavior of \fBgit machete traverse\fP when it needs to act on a branch that is not currently checked out in any worktree.
 .sp
-Set to \fBstay\-in\-the\-current\-worktree\fP to make \fBtraverse\fP stay in whatever worktree has already been reached by that point,
-and check out the branch there instead.
-Note that this worktree might be different then the initial working directory where \fBtraverse\fP started.
+Allowed values:
+.INDENT 7.0
+.IP \(bu 2
+\fBcd\-into\-main\-worktree\fP (default): change directory to the main worktree and check out the branch there.
+.IP \(bu 2
+\fBstay\-in\-the\-current\-worktree\fP: check out the branch in whichever worktree \fBtraverse\fP is currently operating in,
+without changing directory. Note that this worktree might differ from the one where \fBtraverse\fP originally started.
+.IP \(bu 2
+\fBcd\-into\-temporary\-worktree\fP: create a new worktree in a temporary directory, check out the branch there,
+and remove this temporary worktree once \fBtraverse\fP moves on to the next branch (or finishes).
+This ensures that no existing (non\-temporary) worktree has its checked\-out branch changed by \fBtraverse\fP\&.
+.UNINDENT
 .UNINDENT
 .sp
 \fBEnvironment variables:\fP

docs/source/cli/status.rst

@@ -97,6 +97,6 @@ When colors are disabled, relation between branches is represented in the follow
 ``machete.squashMergeDetection``:
     .. include:: git-config-keys/squashMergeDetection.rst
 
-``machete.status.extraSpaceBeforeBranchName``
+``machete.status.extraSpaceBeforeBranchName``:
     .. include:: git-config-keys/status_extraSpaceBeforeBranchName.rst
       :end-line: 3

docs/source/cli/traverse.rst

@@ -173,10 +173,10 @@ This behavior can be customized using ``machete.traverse.whenBranchNotCheckedOut
 ``machete.traverse.fetch.<remote>``:
     .. include:: git-config-keys/traverse_fetch_remote.rst
 
-``machete.traverse.push``
+``machete.traverse.push``:
     .. include:: git-config-keys/traverse_push.rst
 
-``machete.traverse.whenBranchNotCheckedOutInAnyWorktree``
+``machete.traverse.whenBranchNotCheckedOutInAnyWorktree``:
     .. include:: git-config-keys/traverse_whenBranchNotCheckedOutInAnyWorktree.rst
 
 **Environment variables:**

docs/source/git-config-keys/traverse_whenBranchNotCheckedOutInAnyWorktree.rst

@@ -1,7 +1,12 @@
-Controls the behavior of ``git machete traverse`` when checking out a branch that is not currently checked out in any worktree.
+Controls the behavior of ``git machete traverse`` when it needs to act on a branch that is not currently checked out in any worktree.
 
-The default value is ``cd-into-main-worktree``, which means that ``traverse`` will change directory to the main worktree before checking out the branch.
+Allowed values:
 
-Set to ``stay-in-the-current-worktree`` to make ``traverse`` stay in whatever worktree has already been reached by that point,
-and check out the branch there instead.
-Note that this worktree might be different then the initial working directory where ``traverse`` started.
+* ``cd-into-main-worktree`` (default): change directory to the main worktree and check out the branch there.
+
+* ``stay-in-the-current-worktree``: check out the branch in whichever worktree ``traverse`` is currently operating in,
+  without changing directory. Note that this worktree might differ from the one where ``traverse`` originally started.
+
+* ``cd-into-temporary-worktree``: create a new worktree in a temporary directory, check out the branch there,
+  and remove this temporary worktree once ``traverse`` moves on to the next branch (or finishes).
+  This ensures that no existing (non-temporary) worktree has its checked-out branch changed by ``traverse``.

git_machete/__init__.py

@@ -1 +1 @@
-__version__ = '3.39.3'
+__version__ = '3.40.0'

git_machete/client/traverse.py

@@ -1,11 +1,12 @@
 import itertools
+import tempfile
 from enum import auto
 from typing import Dict, List, Optional, Type, Union
 
 from git_machete.annotation import Annotation, Qualifiers
 from git_machete.client.base import PickRoot
 from git_machete.client.with_code_hosting import MacheteClientWithCodeHosting
-from git_machete.code_hosting import PullRequest
+from git_machete.code_hosting import CodeHostingSpec, PullRequest
 from git_machete.config import (SquashMergeDetection,
                                 TraverseWhenBranchNotCheckedOutInAnyWorktree)
 from git_machete.git_operations import (GitContext, LocalBranchShortName,
@@ -49,6 +50,13 @@ def from_string_or_branch(cls: Type['TraverseStartFrom'], value: str,
 
 
 class TraverseMacheteClient(MacheteClientWithCodeHosting):
+
+    def __init__(self, git: GitContext, spec: CodeHostingSpec):
+        super().__init__(git, spec)
+        self.__temporary_worktree_path: Optional[str] = None
+        self.__dir_before_temporary_worktree: Optional[str] = None
+        self.__worktree_root_dir_for_branch: Dict[LocalBranchShortName, str] = {}
+
     def _update_worktrees_cache_after_checkout(self, checked_out_branch: LocalBranchShortName) -> None:
         """
         Update the worktrees cache after a checkout operation in the current worktree.
@@ -60,45 +68,71 @@ def _update_worktrees_cache_after_checkout(self, checked_out_branch: LocalBranch
         current_worktree_root_dir = self._git.get_current_worktree_root_dir()
 
         for branch, path in self.__worktree_root_dir_for_branch.items():
-            if path == current_worktree_root_dir:  # pragma: no branch
+            if path == current_worktree_root_dir:
                 del self.__worktree_root_dir_for_branch[branch]
                 break
 
         self.__worktree_root_dir_for_branch[checked_out_branch] = current_worktree_root_dir
 
+    def _remove_temporary_worktree(self) -> None:
+        if self.__temporary_worktree_path is not None:
+            temp_path = self.__temporary_worktree_path
+            prev_dir = self.__dir_before_temporary_worktree
+            self.__temporary_worktree_path = None
+            self.__dir_before_temporary_worktree = None
+            for branch, path in list(self.__worktree_root_dir_for_branch.items()):   # pragma: no branch; break is always hit
+                if path == temp_path:
+                    del self.__worktree_root_dir_for_branch[branch]
+                    break
+            assert prev_dir is not None
+            print(f"Removing the temporary worktree; changing directory back to {bold(prev_dir)}")
+            self._git.chdir(prev_dir)
+            self._git.worktree_remove(temp_path)
+
     def _switch_branch(
             self,
             target_branch: LocalBranchShortName,
             custom_checkout_message: Optional[str] = None) -> None:
         """
         Switch to the given branch, doing whatever is needed:
         - If branch is already checked out in a worktree, cd there
-        - If branch is not checked out anywhere, checkout the branch (possibly after cd'ing to main worktree)
+        - If branch is not checked out anywhere, checkout the branch (possibly after cd'ing to main or temp worktree)
         - If already on the branch in the correct worktree, do nothing
 
         Updates the worktrees cache after checkout.
         Handles all user-facing messaging including directory changes and checkout messages with "OK".
         """
+        # Clean up temporary worktree from previous branch before switching
+        self._remove_temporary_worktree()
+
         target_worktree_root_dir = self.__worktree_root_dir_for_branch.get(target_branch)
         current_worktree_root_dir = self._git.get_current_worktree_root_dir()
 
         if target_worktree_root_dir is None:
             # Branch is not checked out anywhere
             config_value = self._config.traverse_when_branch_not_checked_out_in_any_worktree()
 
-            # Default behavior: cd to main worktree if we're in a linked worktree
-            # Otherwise (STAY_IN_THE_CURRENT_WORKTREE), stay in the current worktree and checkout the branch there
-            if config_value == TraverseWhenBranchNotCheckedOutInAnyWorktree.CD_INTO_MAIN_WORKTREE:
-                main_worktree_root_dir = self._git.get_main_worktree_root_dir()
-                if current_worktree_root_dir != main_worktree_root_dir:
-                    print(f"Changing directory to main worktree at {bold(main_worktree_root_dir)}")
-                    self._git.chdir(main_worktree_root_dir)
-
-            checkout_msg = custom_checkout_message if custom_checkout_message else f"Checking out {bold(target_branch)}"
-            print_no_newline(f"{checkout_msg}... ")
-            self._git.checkout(target_branch)
-            print(green_ok())
-            self._update_worktrees_cache_after_checkout(target_branch)
+            if config_value == TraverseWhenBranchNotCheckedOutInAnyWorktree.CD_INTO_TEMPORARY_WORKTREE:
+                temp_worktree_path = tempfile.mkdtemp(prefix="git-machete-")
+                print_no_newline(f"Creating a temporary worktree to check out {bold(target_branch)}... ")
+                self._git.worktree_add(temp_worktree_path, target_branch)
+                print(green_ok())
+                self.__dir_before_temporary_worktree = current_worktree_root_dir
+                self._git.chdir(temp_worktree_path)
+                self.__temporary_worktree_path = temp_worktree_path
+                self.__worktree_root_dir_for_branch[target_branch] = temp_worktree_path
+            else:
+                if config_value == TraverseWhenBranchNotCheckedOutInAnyWorktree.CD_INTO_MAIN_WORKTREE:
+                    main_worktree_root_dir = self._git.get_main_worktree_root_dir()
+                    if current_worktree_root_dir != main_worktree_root_dir:
+                        print(f"Changing directory to main worktree at {bold(main_worktree_root_dir)}")
+                        self._git.chdir(main_worktree_root_dir)
+
+                checkout_msg = custom_checkout_message if custom_checkout_message else f"Checking out {bold(target_branch)}"
+                print_no_newline(f"{checkout_msg}... ")
+                self._git.checkout(target_branch)
+                print(green_ok())
+                self._update_worktrees_cache_after_checkout(target_branch)
         else:
             # Branch is already checked out in a worktree - no need to checkout, just cd there
             if current_worktree_root_dir != target_worktree_root_dir:
@@ -151,7 +185,8 @@ def traverse(
         initial_worktree_root = self._git.get_current_worktree_root_dir()
 
         # Fetch worktrees once at the start to avoid repeated git worktree list calls
-        self.__worktree_root_dir_for_branch: Dict[LocalBranchShortName, str] = self._git.get_worktree_root_dirs_by_branch()
+        self.__temporary_worktree_path = None
+        self.__worktree_root_dir_for_branch = self._git.get_worktree_root_dirs_by_branch()
 
         try:
             if opt_start_from == TraverseStartFrom.ROOT:
@@ -515,6 +550,8 @@ def traverse(
                     f"The initial branch {bold(initial_branch)} has been slid out. "
                     f"Returned to nearest remaining managed branch {bold(nearest_remaining_branch)}")
         finally:
+            self._remove_temporary_worktree()
+
             # 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.__worktree_root_dir_for_branch.get(final_branch)

git_machete/config.py

@@ -23,6 +23,7 @@ def _traverse_remote_fetch_key(remote: str) -> str:
 
 class TraverseWhenBranchNotCheckedOutInAnyWorktree(ParsableEnum):
     CD_INTO_MAIN_WORKTREE = auto()
+    CD_INTO_TEMPORARY_WORKTREE = auto()
     STAY_IN_THE_CURRENT_WORKTREE = auto()  # noqa: F841