Below is a patch, that I believe would improve the documentation of git
switch.
The exact new wording is of course open for debate.
Reasoning for the change.
The current doc does not explain why the option is a "forceful" option.
Nor does explain the consequences.
Instead it leaves it to the user to lookup the alternate command, and
find the meaning of
git branch -f newbranch
Only if the user does that successfully, the user may learn about the
full consequences of their actions.
I believe this info should be part of the "git switch" doc, itself.
(Especially due to the severity that the action may have).
From 46580d07f95a18c94925afd141ba55e52a82c8e1 Mon Sep 17 00:00:00 2001
From: Martin <User4martin@xxxxxxxxxxxxxxxxxxxxxxxx>
Date: Tue, 29 Jun 2021 17:22:25 +0200
Subject: [PATCH] Update git-switch.txt
---
Documentation/git-switch.txt | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index 5c438cd5058758..80acafad1f4a46 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -70,8 +70,12 @@ $ git switch <new-branch>
-C <new-branch>::
--force-create <new-branch>::
Similar to `--create` except that if `<new-branch>` already
- exists, it will be reset to `<start-point>`. This is a
- convenient shortcut for:
+ exists, it will be reset to `<start-point>`.
+ This forces the branch to the new location. It also forces
+ any commit hold by the branch to be dropped, unless the
+ commit is also part of any other branch too. You may
+ therefore loose some of your data.
+ This is a convenient shortcut for:
+
------------
$ git branch -f <new-branch>
