Consider replacing "checkout" with "switch" and "restore", if widely available in the future

[twitwi]

git checkout has been confusing for learners (especially when they later discover branching), see https://github.com/swcarpentry/git-novice/issues/169 for a first episode of this discussion.

This summer 2019, git started an experimental feature to solve this issue replacing it with two commands git restore and git switch https://github.blog/2019-08-16-highlights-from-git-2-23/#experimental-alternatives-for-git-checkout

I though this was interesting to share, if people want to try the feature and/or push for its adoptions and/or start thinking about how the lessons might need to be modified.

Cheers.

[peterjc]

Was about to open an issue on this (currently helping during a git session), seems worth considering.

[joaander]

I agree, the new switch and restore commands clearly separate two different tasks into separate commands and will reduce cognitive load on students. I am now using these new commands regularly in my daily work.

However, it will be some time before git 2.23 is generally available to Carpentries workshop students. The workshop template suggests downloading the latest version (currently 2.23) of git on Windows and Mac from the web, and on Linux via their OS's package manager. Ubuntu 18.04 LTS is one popular distribution of Linux which only includes git 2.17. Hopefully, the next LTS release of Ubuntu (20.04 - April 2020) will include git 2.23 or newer, but it may be some time after that before typical Linux systems used by Carpentries students have 2.23 or newer available. Does the Carpentries survey what linux distros students utilize? That information could be helpful in making the decision when to update this content.

I do not plan to submit a PR at this time as it is too early to make the change. Here are the places in the lessons that can be changed once git >=2.23 is generally available.

• 05-history.md - use git restore throughout. Additionally, the warning section "Don’t Lose Your HEAD" can be removed as git restore now only restores files. Even git switch <hash> would not result in this behavior, users need to explicitly opt-in to a detached HEAD with git switch --detach <hash>
• 07-github.md - Remove the reference to git checkout ID. The proper command would be git switch --detach <hash> which has not been taught in prior lessons.
• 09-conflict.md - The solution to "Conflicts on Non-textual files" should use git restore instead of git checkout.

The lesson does not teach branching, so git switch is not needed at all.

[katrinleinweber]

GitForWindows.org is now >2.24. In case you want to add a call-out in the meantime, please feel free to cherry-pick (and adapt) the commit below. Because it's in a fork customised to render from GitLab, I'll not start a PR.

[chendaniely]

I've been teaching git (outside of carpentries related work) and people will still show up with an older version of git even if they're given the setup instructions. but it may be a good idea to still mention checkout as people transition to switch and restore.

One suggestion is to show switch and restore by default, but put in a grey box for the older checkout materials. it's going to take a while before switch and restore hit top StackOverflow solutions, so it may seem worthwhile to keep both sets of commands in the written lesson, but only teach the newer set of functions.

[zingale]

I just ran into this today, teaching the git lesson. The lessons refer to checkout, but the output from the git commands refer to restore. Maybe it is time for this change?

[kekoziar]

@zingale git restore is still experimental

[zingale]

thanks for the response. I guess the bit that was confusing is that as I was sharing my screen and demonstrating it, the message that git gives on my computer says to use "restore", which contradicts what is in the lesson text. So it can be a source of confusion for participants.

[kekoziar]

I'm adding statuses "blocked" and "Refer to Curriculum Advisory Committee" because right now the features of restore and switch are still listed as experimental. As much as I would love to just implement the change in our curriculum, I think feedback and discussion are needed to establish guidelines before implementing changes to include experimental features that may change and/or go away. While I do not think these will change or go away, how we react to them establishes precedent for maintenance of the lesson.

[daviewales]

There's a disccussion on the experimental status of switch and restore on the git mailing list: https://lore.kernel.org/all/[email protected]/T/

It seems likely that the basic functionality which would be shown in a workshop is less likely to change than the more advanced options.

[fiveop]

After the material was ported to the workbench, we could add an instructor note on why checkout is still used and taught.

In addition, we should update the output to correspond to that of the newest version (and maybe mention that it might differ, where appropriate), which refers the user to restore instead of checkout. I do not think we should show both and, given that restriction, it should be least confusing for those that use the newest version.

If others agree, I would prepare a patch that updates all output to that of the current Git version.

[matuskalas]

Personal opinion: I think the time is ripe for finally retiring checkout from the lessons, and replacing with restore and switch. We're teaching our learners for the presence and for the future, and the basic functionality of these is already very stable and the new de-facto standard. (same with main branch, by the way)

[kekoziar]

This will likely be updated with the next full lesson review, if not sooner.

[bienflorencia]

There is an error in the lesson. I'm assuming it derives from this discussion. In the section 'Tracking changes' after Where are my changes?, it says that the output of the console should be

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   mars.txt

no changes added to commit (use "git add" and/or "git commit -a")

However, the actual console output is git restore -- <file>..." to discard changes in working directory). Thus, 'checkout' needs to be replaced with 'restore'.