8000 Inconsistency: Git restore is only used once, rest of book uses reset HEAD · Issue #1487 · progit/progit2 · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Inconsistency: Git restore is only used once, rest of book uses reset HEAD #1487

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
HonkingGoose opened this issue Aug 11, 2020 · 5 comments · Fixed by #1511
Closed

Inconsistency: Git restore is only used once, rest of book uses reset HEAD #1487

HonkingGoose opened this issue Aug 11, 2020 · 5 comments · Fixed by #1511

Comments

@HonkingGoose
Copy link
Contributor
HonkingGoose commented Aug 11, 2020 •
edited
Loading

Which version of the book is affected?

Problem is with the source files, present on current master.

Describe the bug:

Inconsistency in the way to unstage a staged file.
Our examples use use git reset HEAD <file to unstage>.
The status output we show is using git reset HEAD, as that is Git's prior advice before the git restore command became a thing.

There's one place where the book uses git restore and it's introduced with commit: dc15a30

Steps to reproduce:

  1. Search for hits on the string git reset HEAD in the book, notice it's used everywhere for git status and unstaging examples the book uses.
  2. Search for hits on the string git restore, notice it's only used once.

Expected behavior:

I expect the book to present a single way to unstage, and be consistent with it, so that readers are never confused.

Options to fix this:

  1. Revert the merge that resulted in the inconsistency: To untrack a tracked file there is a different command now #1338
  2. Revert the merge that resulted in the inconsistency: To untrack a tracked file there is a different command now #1338 plus create a TIP block in an appropriate place in the book with the hint that git restore can be used instead of git reset HEAD.
  3. Change over the entire book to use the newer git restore command, and put a note up in a appropriate place with something to the effect of: "If git restore doesn't work for you, try git reset HEAD.

I'll wait for the maintainers feedback before making a pull request to fix it in one of the three ways listed.

Context:

This kind of issue also crops up with: #1441
@ben
Copy link
Member
ben commented Aug 16, 2020

Sadly we're in a pickle here.

git-restore was introduced with Git 2.25.0. My up-to-date Mac laptop comes with Git 2.24.3 in the box. So if we only tell people to use git restore, many of them won't be able to follow the directions.

On the other hand, it's confusing and confidence-shaking when the output we show in the book is a mismatch with what a user sees when they type in the commands. A user with an up-to-date Git will see the git restore command given as advice on the command line, and our text still includes git reset.

So how do we cut this Gordian knot? I still think the right answer is to talk mostly about git reset (since that's what git restore is built on). Perhaps we should include a section on git restore, but note that it only comes with newer versions.

@HonkingGoose
Copy link
Contributor Author
HonkingGoose commented Aug 16, 2020 •
edited
Loading

This kind of mirrors the problem with git restore that was noted here: #1441.

git-restore was introduced with Git 2.25.0. My up-to-date Mac laptop comes with Git 2.24.3 in the box. So if we only tell people to use git restore, many of them won't be able to follow the directions.

I made a list of Git versions here: #1441 (comment) many operating systems would not have the git restore command yet...

On the other hand, it's confusing and confidence-shaking when the output we show in the book is a mismatch with what a user sees when they type in the commands. A user with an up-to-date Git will see the git restore command given as advice on the command line, and our text still includes git reset.

Yeah it's best if output from the book matches the terminal output, to prevent confusion and loss of confidence, I agree. The advice Git gives you is actually quite helpful here, so I think most users who bother to read the terminal output fully would probably be able to use git restore in a basic fashion.

So how do we cut this Gordian knot? I still think the right answer is to talk mostly about git reset (since that's what git restore is built on).

I also thought there are some use cases not yet covered by git restore, I noticed git restore sometimes says to use git reset instead, if I recall correctly here...
So the sections covering git reset will probably continue to be helpful. 👍

Perhaps we should include a section on git restore, but note that it only comes with newer versions.

This would also be a good way to handle this! I would then suggest that the new git restore section is also linked, the first time the book covers git reset. That way a reader following the book can get the needed explanation right away. 😄

@HonkingGoose
Copy link
Contributor Author

@ben Do you want a pull request for this then?

I still think the right answer is to talk mostly about git reset (since that's what git restore is built on). Perhaps we should include a section on git restore, but note that it only comes with newer versions.

@ben
Copy link
Member
ben commented Aug 28, 2020

Sure!

@HonkingGoose
Copy link
Contributor Author
HonkingGoose commented Aug 28, 2020 •
< 95FF summary class="btn-link no-underline color-fg-muted js-notice">
edited
Loading

Will do.

@HonkingGoose HonkingGoose mentioned this issue Aug 29, 2020
Merged
2 tasks
@ben ben closed this as completed in #1511 Sep 25, 2020
@HonkingGoose HonkingGoose mentioned this issue Sep 25, 2020
Open
5 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Create section git restore
2 participants
@ben @HonkingGoose
0