[7.7 Git Tools - Reset Demystified] - git reset with mode flag and pathspec

Open book/07-git-tools/sections/reset.asc and read the “Reset With a Path” section around the linked syntax snippet. Rephrase the explanation so it does not suggest that --soft or --hard can be combined with a pathspec, then review the related git-reset documentation for consistency.

General overview of your idea.

The section Reset With a Path illustrates the use of the reset command in the forms including a <pathspec>. It reads well and the example is clear but there is this snippet about the syntax that I think might be slightly confusing:

This form (since you did not specify a commit SHA-1 or branch, and you didn't specify `--soft` or `--hard`) is shorthand for `git reset --mixed HEAD file.txt`...

Using --soft or --hard in this form would actually raise an error (which makes sense) but the current wording makes it sound like they could have been valid choices. I was surprised to see that --mixed is allowed (even if it triggers a deprecation warning) but I guess that this implementation detail is the reason why the git-reset documentation does not explicitly preclude the use of a <mode> alongside a <pathspec>.

I can see why elaborations around --mixed were dropped there for the sake of clarity, so I think the snippet above would also become clearer if mentions to <mode> were dropped altogether.

What problem will this solve?

The example in this section is good as it is, but some rephrasing would avoid potential confusion around mixing <mode> with <pathspec>, and also it would improve alignment between this section and the related documentation.

Have you thought about other solutions?

I'd say it’s quite clear that the git-reset documentation encourages the use of <mode> only in the form:

git reset [<mode>] [-q] [<commit>]

without elaborating on the caveat that --mixed could be used beyond this case.

In the same spirit, I think that the snippet above could benefit from being rephrased to something along the lines of:

This form (since you did not specify a commit SHA-1 or branch) is shorthand for `git reset HEAD -- file.txt`…

and perhaps adding a note with the caveat around --mixed if it's not too convoluted.

Would this be worth a pull request? I know a related issue was closed some years ago but in this case my point is not the warning when specifying --mixed.

Do you want to help with this enhancement idea?

Yes