4 ms·

I think git's UI is terrible for one main reason: each git (porcelain) command can do a whole bunch of unrelated things. Want to switch to a different branch (

I think git's UI is terrible for one main reason: each git (porcelain) command can do a whole bunch of unrelated things. Want to switch to a different branch (or tag/revision hash)? 'git checkout' Want to change a single file's contents to a previous version? 'git checkout' Want to create a new branch? 'git checkout' This becomes a problem because 'git checkout' has to have many different options to be able to do all of these things and all of these options can interact in different ways. This makes the 'git help' for every command enormous because it needs to document the interaction between all the different options. Large help docs are hard to read when you're in the middle of working and just want to know how to do something specific. Contrast git's help with Mercurial's equivalent helps: $ git help checkout | wc -l 236 $ (hg help update ; hg help branch ; hg help revert) | wc -l 100 Mercurial's docs are less than half the length of git's. This isn't because Mercurial isn't well documented -- it's because Mercurial splits up functionality into small, independent commands that do one main thing each. Mercurial's help doesn't need to waste time saying stuff like "if you use --foo then --bar means X, but if you use --bar on its own it means Y, and neither of them can be used with --baz". This is why I hate git's UI. There's so much functionality crammed into every command that the docs for each command become impossible to scan (try 'git help log | wc -l' for laughs).

moe 17y ago
This is the best summary of the fundamental problem with the git UI that I have ever read. I'm feeling exactly the same but never managed to put my finger on it as perfectly as you just did. Thank You!
chousuke 17y ago
If you think of "git checkout" as "update the working copy", doing all those things with a single command makes a lot of sense. The "create a new branch" functionality doesn't really belong in your list, since branches are created with "git branch". The -b switch is provided for checkout because _updating the working copy_ and creating a new branch is a very common sequence. To be honest, I have yet to find anything I particularly dislike about git's approach. For some things, it took a while to see why it is the way it is, but in the end I find it fairly sensible. In my opinion, git just does things right on a fundamental level[1], which I find more important than UI issues. [1] Compared to hg, especially the 'a branch is just a pointer' approach. I know of the bookmarks extension for hg but in the end I just used hg-to-git for the one hg repository that I follow.
- stevelosh 17y ago
  > If you think of "git checkout" as "update the working copy", doing all those things with a single command makes a lot of sense. The problem is that "update the working copy" isn't accurate. When you 'git checkout my-feature-branch' you "update the working copy" AND "switch the current branch to my-feature-branch". When you 'git checkout fa230bc -b new-branch' you "update the working copy" AND "create a new branch". > The "create a new branch" functionality doesn't really belong in your list, since branches are created with "git branch". The -b switch is provided for checkout because _updating the working copy_ and creating a new branch is a very common sequence. It absolutely does belong in the list. The problem is not simply that 'git checkout' can do a lot -- it's that the documentation is very hard to scan because it can do a lot. Adding the -b switch adds to the problem because now you have to mention how this option interacts with the others (and give examples of how to use it in the Examples section). Sure, if I want to create a new branch at a specific revision then the -b switch saves me a few keystrokes -- but it also makes the documentation for 'git checkout' harder to quickly find what I'm looking for whenever I want to look up something, even if it's completely unrelated to branch creation.
  - aphyr 17y ago
    I always looked at -b this way: git checkout <branch> updates my working copy to some branch. -b just means "Implicitly create the branch if it doesn't exist yet."

moe 17y ago

This is the best summary of the fundamental problem with the git UI that I have ever read. I'm feeling exactly the same but never managed to put my finger on it as perfectly as you just did. Thank You!

chousuke 17y ago

If you think of "git checkout" as "update the working copy", doing all those things with a single command makes a lot of sense. The "create a new branch" functionality doesn't really belong in your list, since branches are created with "git branch". The -b switch is provided for checkout because _updating the working copy_ and creating a new branch is a very common sequence. To be honest, I have yet to find anything I particularly dislike about git's approach. For some things, it took a while to see why it is the way it is, but in the end I find it fairly sensible. In my opinion, git just does things right on a fundamental level[1], which I find more important than UI issues. [1] Compared to hg, especially the 'a branch is just a pointer' approach. I know of the bookmarks extension for hg but in the end I just used hg-to-git for the one hg repository that I follow.

stevelosh 17y ago
> If you think of "git checkout" as "update the working copy", doing all those things with a single command makes a lot of sense. The problem is that "update the working copy" isn't accurate. When you 'git checkout my-feature-branch' you "update the working copy" AND "switch the current branch to my-feature-branch". When you 'git checkout fa230bc -b new-branch' you "update the working copy" AND "create a new branch". > The "create a new branch" functionality doesn't really belong in your list, since branches are created with "git branch". The -b switch is provided for checkout because _updating the working copy_ and creating a new branch is a very common sequence. It absolutely does belong in the list. The problem is not simply that 'git checkout' can do a lot -- it's that the documentation is very hard to scan because it can do a lot. Adding the -b switch adds to the problem because now you have to mention how this option interacts with the others (and give examples of how to use it in the Examples section). Sure, if I want to create a new branch at a specific revision then the -b switch saves me a few keystrokes -- but it also makes the documentation for 'git checkout' harder to quickly find what I'm looking for whenever I want to look up something, even if it's completely unrelated to branch creation.
- aphyr 17y ago
  I always looked at -b this way: git checkout <branch> updates my working copy to some branch. -b just means "Implicitly create the branch if it doesn't exist yet."