[7.7 Git Tools - Reset Demystified] - git reset with mode flag and pathspec
Nobody has claimed this yet.
Assessment
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Newbie friendliness
- 55/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Stale
- Tech stack
- git
- Domain
- documentation
Research direction
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.
Written by the indexing model from the issue text.
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
- Dominant language
- CSS
- Stars
- 6.6k
- Forks
- 2.1k
- PR merge metrics
- No merged PRs in 30d
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from progit/progit2
-
Difficulty 1/5 Under an hour Newbie friendliness 87/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
enhancement
Difficulty 1/5 Under an hour Newbie friendliness 82/100
Similar issues
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
AI-Agent/Queued Type/Bug
Difficulty 1/5 Under an hour Newbie friendliness 91/100
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 92/100
-
approved documentation
Difficulty 1/5 Under an hour Newbie friendliness 89/100
vitest-dev/vitest#12015 · 4 comments ·
Maintainers usually reply within 1 day
-
Pri3
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
MicrosoftDocs/windows-dev-docs#6205 ·