Re: [PATCH v6] unpack-trees: suggesting 'git checkout -m' with its repercussions

[Junio C Hamano <gitster@pobox.com>]

"Arsh Srivastava via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Arsh Srivastava <arshsrivastava00@gmail.com>
>
> This comment is an extention to the already existing stash comment.
> Added updated comment over the already existing function
> "setup_unpack_trees_porcelain" with "git checkout -m"
> and its repercussions
> I have also mentioned the repercussions of using "-m".
>
> Signed-off-by: Arsh Srivastava arshsrivastava00@gmail.com

The commit message should focus on the "why" and "what" from a user
perspective, following the project's standard format (problem
description, then solution).

Consider a more standard phrasing:

    unpack-trees: suggest 'git checkout -m' when checkout fails

    When a branch switch fails due to local changes, we suggest
    stashing or committing. However, 'git checkout -m' is a valid
    alternative for users who wish to carry their changes over via a
    merge.

    Update the advice message to suggest this option, while
    including a warning about the potential for data loss if a hard
    reset is performed after a conflicted merge.

Also, note that "extention" is a typo; it should be "extension".

Having said that, I am not sure if we want to suggest "checkout -m"
in this situation after all.

The added message is quite long:

> Try using 'git checkout -m <branch>' for a quick fix.
> Please Note :- that using -m (merge) will not save your changes,
> rather would directly merge them.
> Meaning if you are not able to resolve conflicts and does --hard
> reset your local changes would be gone.

When advice requires a multi-line warning about potential data loss,
it's often a sign that the operation being suggested isn't suitable
for general advice. The goal of these messages should be to provide
a clear, safe next step, not a list of advanced alternatives with
caveats. After all, the users who need such an "it failed, now what
should I do to recover?" message the most are relatively
inexperienced users and we do not want the advice to be
overwhelming.

The primary concern is that 'git checkout -m' is a high-stakes
operation compared to 'git stash'.

- When a user uses 'git stash', their changes are recorded in a
  stash entry. If 'git stash pop' later results in conflicts they
  cannot resolve, the user can always 'git reset --hard' to get back
  to a clean state, knowing their original changes are still safe in
  the stash entry, which they can re-attempt to use later.

- In contrast, 'git checkout -m' performs the merge directly in
  the working tree.  If conflicts arise, the original local changes
  are immediately replaced by conflict markers. Unlike stash, there
  is no "undo" record. If the user realizes they are in over their
  head, they cannot simply "abort" to get their original changes
  back. They have only one chance to resolve it correctly, and they
  have to do so right there.

Suggesting this "one-shot" approach to a user who is already in a
state of friction (and likely less experienced) might be providing
them with a "foot-gun" rather than a helpful tip. Generally, advice
that nudges users toward the safest "golden paths" like stashing or
committing is preferred.

For a microproject, you've successfully demonstrated that you can
modify the advice system and update the test suite. However, for the
health of the project's usability, it might be better to drop the
'checkout -m' suggestion and instead focus on making the existing
'stash' and 'commit' advice as clear and helpful as possible.

Thanks.