Description
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