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

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

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:

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.