Unclear description of git restore -s vs git revert

[astroDimitrios]

How could the content be improved?

In the Reverting a committ challenge there is a paragraph:

The command git revert is different from git restore -s [commit ID] . because git restore returns the files not yet committed within the local repository to a previous state, whereas git revert reverses changes committed to the local and project repositories.

Which is hard to understand, we are considering changing it to:

The command git revert is different from git restore -s [commit ID] .. git restore restores files within the local repository to a previous state, whereas git revert restores the files to a previous state and adds then commits these changes to the local repository. So git revert here is the same as git restore -s [commit ID] followed by git commit -am Reverts: [commit].

So it's clearer what the difference is between the two commands.

Which part of the content does your suggestion apply to?

https://swcarpentry.github.io/git-novice/05-history.html

[martinosorb]

I think this is a fair point, but it misses a key difference between the two: restore is primarily used to restore previous version of given files (all, if we really want, but that's a special case), whereas revert is used to entirely undo a commit. I think we are depicting them as more similar than they actually are: while they do similar things in the specific case mentioned, their use cases are quite different.

This is what the git documentation states:

git-revert[1] is about making a new commit that reverts the changes made by other commits. git-restore[1] is about restoring files in the working tree from either the index or another commit. This command does not update your branch. The command can also be used to restore files in the index from another commit.

So I suggest we keep it simple and change that paragraph to

The command git revert is different from git restore -s [commit ID] . in that revert makes a new commit that undoes the changes made by a previous commit, whereas restore returns files to a previous state, but without committing. restore can also be used on individual files.

What do you think?