Both the first and the second are variants of the same action: make part of a workspace (defaulting to all of it) represent the specified point in the repository (defaulting to the current branch).

The first one is selecting a subset of the repository, exactly one file, and making the filesystem copy contain the contents that are in HEAD.

The second one makes the whole repository look like a different branch.

The third is just the second, along with a branch operation (which is weird to combine in it).

I’ll agree with you, though, just for a different command: git reset. That is a command that truly can’t be described in one sentence.

I think your comment illustrates well the problem. It was straightforward for me to understand what jfim said. It took a fair amount of effort to process your comment.

And the generalized (n variables) Taylor's theorem takes more effort to process than its single variable version.

If there was a command line tool for Taylor's theorem,I would prefer the one with generalized interface instead of the one that arbitrarily decided that n=1 was the standard case.

Actually, you may not prefer the generalized interface once you see it, as summarized by the immortal Joel Spolsky:

https://www.joelonsoftware.com/2001/04/21/dont-let-architect...

> When great thinkers think about problems, they start to see patterns. They look at the problem of people sending each other word-processor files, and then they look at the problem of people sending each other spreadsheets, and they realize that there’s a general pattern: sending files. That’s one level of abstraction already. Then they go up one more level: people send files, but web browsers also “send” requests for web pages. And when you think about it, calling a method on an object is like sending a message to an object! It’s the same thing again! Those are all sending operations, so our clever thinker invents a new, higher, broader abstraction called messaging, but now it’s getting really vague and nobody really knows what they’re talking about any more. Blah.

Or to put it another way, in this case git commands reflect what git needs to do, but hg commands reflect what the user wants to achieve. Which aligns with the "better UX" comments.

This has to be the top UX failure mode. Presenting the user with the abstractions we cleverly made in the code to factorize the architecture, instead of overlaying them with a different set of user-friendly abstractions.

It does make sense from that perspective (which seems to be modeled on cvs update), thanks for sharing it.

Both mercurial and subversion have update do the same thing (update the working copy to be the same as the one stored in the source control), and a revert verb (revert a file in the working copy to be the same as the one in the source control). Cvs and git instead use a single verb (update/checkout) for updating the entire tree or a set of files to a given revision. Interesting!

To be fair, there is "git branch <somebranch>" to create a new branch. Then you'll have to checkout that branch if you want to use it.

Your third git example above just combines those two operations into a single command as a convenience.

That's true, but from my perspective it makes more sense to attach combined operations to the first operation, not the following one.

For example, the equivalent of git fetch (fetch remote code without updating the working copy) is hg pull, while the equivalent of git pull (fetch remote code and update the working copy) is hg pull -u (pull, then update).

In my opinion, and this can be debated, is that it makes more sense to attach it to the first operation, since one would look at the documentation of the first command (how do I fetch the remote code?) then see that the working copy can be updated as part of that. The git documentation does mention git checkout -b as part of the git branch documentation, though.

Maybe this is just a rant against git though, at the end of the day, as long as work gets done, use whatever tools work for you. :-)