Rewrite recommend `git restore` instead of `git reset`

[HonkingGoose]

Which version of the book is affected?

This will affect our mainline branch, when macOS and Debian stable include newer versions of Git that have the git restore command.

Describe the bug:

When stable platforms use newer versions of Git, we should not be using git reset as the recommended way to do things, and instead promote git restore usage whenever possible.

Steps to reproduce:

Just look through the book and note that we use git reset instead of git restore.

Expected behavior:

What the rewrite should do:

• [ ] Rewrite book to use git restore instead of git reset where possible.
• [ ] Use git restore where Git recommends we use it.
• [ ] Use git restore to unstage things.
• [ ] Add [NOTE] explaining that git reset is the "old way" of doing things.
• [ ] Clarify difference between restore and reset, and when you should use each of those commands.

Screenshots:

Additional context:

We have also discussed Git restore at the following places:

• #1441
• #1487

[HonkingGoose]

@ben @prosoitos Here is the issue discussing the rewrite to recommend git restore instead of git reset.

[thiagola92]

I would love to change while reading the book but i don't know if we are still waiting something.

I have to say that it was a little weird to read about git restore right after reading about git reset HEAD <file>…​ and git checkout -- <file>. Maybe the text telling about the change would be better before starting this topic, this way people can skip the section that doesn't match their Git version.

I'm in favor to change to git restore because this page seems a lot like a copy paste in most of the text.

[HonkingGoose]

I would love to change while reading the book but i don't know if we are still waiting something.

Thank you for offering to help improve the book!

We're only waiting for Debian and macOS to come with a version of Git that has the git restore command. I'm talking about the out-of-the-box version of git, after you've fully upgraded your Debian LTS of upgraded to the latest macOS. Users can always get a newer version of Git from source, or from special PPA repositories. But we're aiming for normal users, who just use the version of Git that comes with their operating system.

Maybe Debian LTS and macOS latest version now have the correct version of Git?

I have to say that it was a little weird to read about git restore right after reading about git reset HEAD <file>…​ and git checkout -- <file>. Maybe the text telling about the change would be better before starting this topic, this way people can skip the section that doesn't match their Git version.

I'll let @ben figure out what to do here. 😉

[VODINHCUONG]

Hay cấp nhat

[HonkingGoose]

Version of Git for Debian 11

Looks like Debian 11 now comes with Git version 2.30.2 out of the box, and has 2.39.1 in Backports. ^repology

The GitHub Blog mentions that Git version 2.23 introduced the git restore command. ^gh-blog

So Debian 11 should have access to git restore out of the box.

Version of Git for macOS

There are multiple ways to get Git on macOs. ^git-scm-macos

Homebrew

People that use Homebrew get 2.39.1 ^repology which is also good to go.

When installing Xcode

I don't know what version of Git comes with a fresh install of Xcode...

[ben]

I'm on a mac with the latest OS, and:

❯ /usr/bin/git --version
git version 2.37.1 (Apple Git-137.1)

So I think we're ready to make this change now.