[Suggestion]: Update 2.4 Git Basics - Undoing Things section with `git restore`

[prosoitos]

I'd be happy to submit a PR on this if people are ok with the change.

2.4 Git Basics - Undoing Things has fallen out of date now that git restore <file> is suggested instead of git checkout -- <file> to get rid of changes in unstaged files.

The paragraph "Unmodifying a Modified File" of that page, which predates the launch of the new command git restore, does not reflect the current version of Git anymore. I would be happy to update this, but I wanted to make sure the book authors agreed with this first (particularly since the old command still works and there is an experimental warning in the git-restore man page).

[prosoitos]

Actually, I just realized that the section "Unstaging a Staged File" would require a similar update since the recommended way to unstage a file, since the addition of the git restore command, is git restore --staged <file> instead of the old git reset HEAD <file>.

[ben]

Yeah, that sounds like a positive change for sure. I'd love to see a PR!

[prosoitos]

Excellent 🙂

I'll do this in the coming week or so.

[HonkingGoose]

Hi @prosoitos good catch!

I noticed the change from git reset and git checkout -- to git restore would touch quite a lot of files:

• String git reset gets 52 hits in 16 .asc files.
• String git checkout -- 24 hits in 9 .asc files.

I also think that the old undo actions have more references that won't show up with only those 2 string searches. So I strongly suspect that you would need to search for all hits on git checkout and git reset to ensure you got 'em all... 😄

If you want, we could split the work between us, and work together on a branch? So that you're not having to do this bunch of work alone?

[prosoitos]

Thanks for the heads-up @HonkingGoose.

On my side, I also realized that git switch, which is the other command git checkout got split into in 2.23 isn't included in the book either. It would make sense to add both of them at the same time.

Since the behaviour of the old git checkout commands (and git reset) haven't changed with the addition of git restore and git switch, the book is still showing commands which work. (The only place where the book has become incorrect is in the suggestions that Git gives when you run git status). So it may not be as critical to be exhaustive as if the old commands had been broken by version 2.23. Also, since the old commands are still working and since many people run older versions of Git, I am now thinking of adding the new commands instead of replacing the old by the new (I just taught a git workshop and I had the new commands in my website and that threw some new users running an older Git totally off. Even the clusters of the company I work for have a version of Git anterior to 2.23. So a fair number of people don't have access to the new commands yet. So having both options with version-specific information is, I now think, the most useful approach for users of the book).

I haven't gotten to this yet as I am very busy at work, but after July 10, I will have a break at work and I will have time to really focus on this. If you were ok with this, I would be happy to give this PR a try in the days following July 10 and you are welcome to make changes to my work then.

As a first step, I am thinking of simply editing the pages on undoing things (correcting the output of git status and adding the new option of using git restore) and on branches (adding the new option of using git switch). Not sure yet where to move from there as I haven't given it any thought, so I'll be happy to chat with you about the other files once I have done that first step 🙂

[ben]

My recommendation is that while there's a non-trivial chance that our readers will be running a version of Git that doesn't include switch, we add a NOTE section saying "there's an easier way of doing this." When it's reasonably certain that everybody can use the new commands, that's when we can remove references to git checkout -- <file>.

These commands were introduced in Git 2.27, but my MacOS system (the latest 10.5.5) comes bundled with Git 2.24.3, so we're not there yet. Most people will update Git, but some will not, and we don't want them to have a super frustrating experience as they're trying to learn.

[prosoitos]

Exactly!

[Morganov]

I agree with @ben that a NOTE will be enough. Additionally, there is the note in section 1.5 that the book was written using git version 2.8.0.

[HonkingGoose]

I've checked what versions of git you will get on the most used distros/operating systems. I'm making the assumption that people will use the latest version that their OS offers via the update channels normally available.

Source of data: https://repology.org/project/git/versions

Fully up to date with upstream:

Upstream Git project 2.27.0
OpenSuse Tumbleweed: 2.27.0
Manjaro Stable: 2.27.0
Arch: 2.27.0
Gentoo: 2.27.0
Chocolatey: 2.27.0
Homebrew: 2.27.0
Git for Windows project: 2.27.0
Debian Testing/Unstable/Experimental: 2.27.0

One version behind:

OpenSuse Leap 15.2: 2.26.2
Fedora 32: 2.26.0
Debian Stable Backports: 2.26.2

More than 1 version behind:

Ubuntu 20.04 LTS: 2.25.1
MacOS (10.5.5): 2.24.3
Debian Stable (default): 2.20.1

Outdated:

CentOS 8: 2.18.1
Ubuntu 18.04 LTS: 2.17.1
Ubuntu 16.04 LTS: 2.7.4

[prosoitos]

Additionally, there is the note in section 1.5 that the book was written using git version 2.8.0.

Ah! I totally missed that. This changes my perspective on this a lot. Thank you @Morganov for pointing this out!

With this in mind, I fully agree that adding git restore and git switch as notes is the best approach at this point.

This is really why I opened this issue before submitting a PR 🙂 So thank you for your thoughts on this.

[HonkingGoose]

@ben Do you want me to create a new issue like #1524 but for a git restore rewrite? So that you can close this issue after merging #1515 and #1523.

I'll incorporate the discussion we had on git restore in this issue into the new issue. That way we are not losing relevant discussion, but do separate out the git restore and git switch rewrites.

Let me know what you like. 😉