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

Open
#2,031 0 comments 0 reactions 0 assignees View on GitHub

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

enhancement
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

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from progit/progit2

All issues in progit/progit2

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.