Re* [PATCH v3] checkout/switch: disallow checking out same branch in multiple worktrees

Commit Message

Junio C Hamano Jan. 19, 2023, 7:23 a.m. UTC

Carlo Marcelo Arenas Belón  <[e-mail]> writes:

> Changes since v2
> * A leak free implementation

> * More details in commit as suggested by Junio

I meant to say we may need more details in the documentation, but
after reading the existing documentation, we say that

 - "-B <name>" is equivalent to run "branch -f <name>", which is
   sufficient to hint that it will fail to recreate and check out an
   existing branch that is checked out elsewhere, because "branch
   -f" would fail in such a situation.

and that

 - "--ignore-other-worktrees" defeats the safety that makes "git
   checkout refuses when the wanted ref is already checked out".

so the existing documentation of "git checkout" may already be OK.

As long as it is well known that "git branch -f" still fails in the
situation, that is.  After re-reading "git branch --help" twice,
however, I am not sure if it is so clear, though.

How about adding something like this, as an independent
documentation improvement?

----- >8 --------- >8 --------- >8 --------- >8 -----
Subject: [PATCH] branch: document `-f` and linked worktree behaviour

"git branch -f name start" forces to recreate the named branch, but
the forcing does not defeat the "do not touch a branch that is
checked out elsewhere" safety valve.

Signed-off-by: Junio C Hamano <[e-mail]>
---
 Documentation/git-branch.txt | 4 ++++
 1 file changed, 4 insertions(+)

Comments

Carlo Marcelo Arenas Belón Jan. 19, 2023, 7:41 a.m. UTC | #1

Thanks, that should round up the documentation for this behaviour nicely.

Carlo

Patch

diff --git c/Documentation/git-branch.txt w/Documentation/git-branch.txt
index aa2f78c4c2..b12e7940d3 100644
--- c/Documentation/git-branch.txt
+++ w/Documentation/git-branch.txt
@@ -123,6 +123,10 @@  OPTIONS
 	points to a valid commit. In combination with
 	`-m` (or `--move`), allow renaming the branch even if the new
 	branch name already exists, the same applies for `-c` (or `--copy`).
++
+Note that 'git branch -f <branchname> [<start-point>]' refuses to change
+an existing branch `<branchname>` that is checked out in another worktree
+linked to the same repository.
 
 -m::
 --move::