Subject: Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section

From: Junio C Hamano <[email-masked]>
Date: Fri, 12 Sep 2025 09:23:14 -0700

"Julia Evans" <[email-masked]> writes:

> Do you think that the concept of a "pathspec" is especially useful/powerful
> in the case of `git checkout`?

In a project that organizes its files reasonably cleanly, after
doing a random explory development to reach a good stopping point, a
user would realize that changes to subdirectory X and Y are good but
changes to subdirectory Z are all useless, in which case of course
"git checkout Z" (from the index, if you haven't done 'git add' to
record interim state to the index), or "git checkout HEAD Z" (to get
back to the pristine state) would be especially useful/powerful.

Of course, all the commands that take pathspec gain its benefits
equally well, like "git grep -e pattern ':!not-here/'" to find
pattern from everywhere except somewhere, "git log -p Doc/" to see
changes that touched subset of paths, "git reset Z/" to undo earlier
series of "git add"s only for the specified subset of paths.

If you are trying to find a command that new people are likely to
first benefit from pathspec, I tend to think 'checkout' is not one
of them.  Be it 'reset' or 'checkout', the form with pathspec is
typically used to undo the effect of earlier 'add' with pathspec, so
in that sense, if we want to give a quick tutorial for pathspec to
newbies in the documentation for a single command, 'add' probably is
more appropriate than 'checkout'.