Re: [PATCH] git-checkout.txt: Document "git checkout <pathspec>" better

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 10, 2015, 16:38 UTC
Message-ID: <xmqq7frbmsce.fsf@gitster.dls.corp.google.com>
In-Reply-To: <loom.20150610T170737-586@post.gmane.org>

Ed Avis <eda@waniasset.com> writes:

> 'restore' may be more consistent with git's internal terminology.
> But from an outsider's perspective, 'revert' rather than 'restore' is in my
> view much clearer and more consistent with other version control systems:
> for example 'svn revert' is what you use to revert files in the working copy.

The reason why I said "restore" is because it does *not* have any "internal terminology" connotation.

On the other hand, "revert" that means "create a counter-effect commit" is not "internal". "git revert" is a part of end-user facing command.

The only people that will be helped by using "revert" there will be the ones who haven't learned "git revert". And it will make it harder for them to learn "git revert". It is unfortunate that other systems use the word "revert" in a different way, and that is why we should avoid using that word when describing "checkout".

Show 6 quoted lines

> The original issue was that I naively expected that 'git checkout PATH' would
> indeed just 'restore' some files, that is, create them when they are missing.
> ...
> If 'revert' is not a suitable verb because of the existing git-revert, then
> I suggest that 'overwrite' or 'replace' might better convey the idea of what
> the command does.

Git is about "contents", not "files". You modify a file, and restore its contents to its pristine state. It is not "restore the file", as Git is not about "files".

I think "overwrite is better" is primarily coming from not thinking in terms of "Git tracks contents, not files".