Why does git-checkout accept a tree-ish?

Why does git-checkout accept a tree-ish?

[Dan Fabulich]

I was looking back through git's history, trying to figure out why git-checkout has so many features. I was struck by this commit by Junio in 2005.

https://github.com/git/git/commit/4aaa702794447d9b281dd22fe532fd61e02434e1

> git-checkout: revert specific paths to either index or a given tree-ish.
> When extra paths arguments are given, git-checkout reverts only those
> paths to either the version recorded in the index or the version
> recorded in the given tree-ish.
> 
> This has been on the TODO list for quite a while.

Prior to this commit, git-checkout would only switch branches; you could use git-checkout-index to copy files from the index to the working tree. But in this commit, git-checkout not only subsumes the functionality of git-checkout-index but also learns the ability to copy files from an arbitrary branch (now an arbitrary tree-ish) into the working copy *and* the the index. (That was important because git-reset didn't accept <paths> in 2005.)

I think the "UNIX philosophy" would have advocated that a new command be created to handle this case, perhaps something like git-checkout-tree. (That would also have eliminated the need to use -- to disambiguate the tree-ish from the paths.)

And so I wonder if anybody knows just why git-checkout gained these two features in one commit, without creating a separate command.

I have two guesses:

1) It was pretty easy for Junio to implement as part of git-checkout; just 20 lines of code and a small test.

2) git at the time was distributed as a collection of files, git-checkout, git-reset, etc. and so there was some pressure not to create a new command for fear that it would clutter the filesystem.

Are those the actual reasons? (This seems like it might be a FAQ, but Google failed me searching for git faqs or "why does git checkout do so many things.")

-Dan

P.S. I would make a similar argument about adding <paths> support to git-reset, rather than creating a separate command like git-unadd.

https://github.com/git/git/commit/2ce633b928f78224a37308f45810e76fefe8df56
It was documented a couple of weeks later on Dec 26.
https://github.com/git/git/commit/6934dec89538e054823aadcce08af040bc8dcf79

Re: Why does git-checkout accept a tree-ish?

[Junio C Hamano]

Dan Fabulich <dan@fabulich.com> writes:

> I was looking back through git's history, trying to figure out why
> git-checkout has so many features. I was struck by this commit by
> Junio in 2005.
>
> https://github.com/git/git/commit/4aaa702794447d9b281dd22fe532fd61e02434e1
>
>> git-checkout: revert specific paths to either index or a given tree-ish.
>> When extra paths arguments are given, git-checkout reverts only those
>> paths to either the version recorded in the index or the version
>> recorded in the given tree-ish.
>> 
>> This has been on the TODO list for quite a while.
>
> Prior to this commit, git-checkout would only switch branches; you
> could use git-checkout-index to copy files from the index to the
> working tree. But in this commit, git-checkout not only subsumes
> the functionality of git-checkout-index but also learns the
> ability to copy files from an arbitrary branch (now an arbitrary
> tree-ish) into the working copy *and* the the index. (That was
> important because git-reset didn't accept <paths> in 2005.)
> ...
> And so I wonder if anybody knows just why git-checkout gained
> these two features in one commit, without creating a separate
> command.

The whole thread would explain it, I think.

https://public-inbox.org/git/Pine.LNX.4.64.0510171814430.3369@g5.osdl.org/#t

Re: Why does git-checkout accept a tree-ish?

[Junio C Hamano]

Dan Fabulich <dan@fabulich.com> writes:

> Prior to this commit, git-checkout would only switch branches; you
> could use git-checkout-index to copy files from the index to the
> working tree. But in this commit, git-checkout not only subsumes
> the functionality of git-checkout-index but also learns the
> ability to copy files from an arbitrary branch (now an arbitrary
> tree-ish) into the working copy *and* the the index. (That was
> important because git-reset didn't accept <paths> in 2005.)
> ...
> P.S. I would make a similar argument about adding <paths> support
> to git-reset, rather than creating a separate command like
> git-unadd.

I do not have a habit of crying over spilt milk for too long, but if
we did not have "git reset <paths>..." and adding an equivalent
feature today, I would guess that we would not have done it as a
different mode for "git reset".  We probably wouldn't have added an
extra command "unadd", either.

"git checkout --cached [<tree-ish>] <paths>..." would have been more
in line with the CLI convention for a command that can act on the
index and/or the working tree files ("--cached" is the way to make a
request to act only on the index without affecting the working tree
files).

As to why "git checkout" started taking <paths>, the thread referred
to in my previous response seems to give a better story than I could
remember ;-).  We were unhappy with checkout-index and the
suggestion that was first made publicly reused "git checkout".
While I initially showed my reluctance by calling the hypothetical
command "xxxxxx" instead of Linus's suggested overloading of
"checkout" in my response in the thread, I think the end-result
turned out to be not too bad, given that our users understand the
difference between 

 - checking out a branch to work on advancing the history of the
   branch; and

 - checking out a set of paths out of a <tree-ish> to modify the
   working tree contents while working on advancing the history of
   the current branch.

just fine.  When doing the former, you would of course want to
preserve local modifications in your working tree.  When doing the
latter, you are asking to overwrite the named paths (checking them
out of a tree-ish or the index is often done to wipe the mistaken
attempt to modify it and giving you a clean slate).