Git koans

Git commands are not consistent. This is a result of it growing organically, and having a maintainer who strongly values backwards compatibility. But you know, having used git for years that doesn't bother me. Let me explain.<p>Git is conceptually straightforward[1]. It is difficult if not impossible to discern those concepts from its baroque CLI. So learning git from its built-in help and/or man pages is suboptimal if not a complete waste of time. Either read the Pro Git book[2] or pop the hood[3]. Then the inconsistent CLI is no longer a big deal. If it were, someone would have come up with a new porcelain (high-level CLI) that would have taken hold by now. And no one really has. There is Easy Git[4] but I don't know anyone who uses it.<p>And really, I see git as not much different than Unix in this regard. Unix commands vary widely in their usage. Does knowing awk help with sed? cpio and tar? wget vs curl? Eventually you understand concepts such as pipes, regular expressions, file descriptors, etc and you become familiar with the commands where you are able to apply these concepts, at which point does strict interface consistency between them matter? I dunno, but I started with both git and hg around the same time and ended up happier with git. Mercurial had the "better" CLI, but I found git was better at doing what I wanted. Before that I used clearcase, which has a very consistent CLI and yet I was constantly cursing at it.<p>Or maybe I just have stockholm syndrome and I'd feel differently if I'd ever used plan 9. :)<p>1. <a href="http://tom.preston-werner.com/2009/05/19/the-git-parable.html" rel="nofollow">http://tom.preston-werner.com/2009/05/19/the-git-parable.htm...</a><p>2. <a href="http://git-scm.com/book" rel="nofollow">http://git-scm.com/book</a><p>3. <a href="http://newartisans.com/2008/04/git-from-the-bottom-up/" rel="nofollow">http://newartisans.com/2008/04/git-from-the-bottom-up/</a><p>4. <a href="http://people.gnome.org/~newren/eg/" rel="nofollow">http://people.gnome.org/~newren/eg/</a>

Context<p>---<p>Master Git and a novice API developer stood together in a crowded office.<p>"I am trying to merge two massive XML files," explained the API developer, "and I am getting many tedious conflicts. You must have a strategy for making the lines match up in a human-readable manner. What is my best option?"<p>"Patience," said Master Git, turning away from the monitor.<p>"But I have been manually resolving for hours!" protested the API developer. "My mergetool ought to be able to imply context and match lines properly!"<p>Master Git sighed and left the room without a word. Hours later, he returned to find the office empty and silent. Only the API developer remained, his head bowed in defeat before the monitor.<p>"git merge --strategy-option=patience," whispered Master Git.<p>Upon hearing the same word in explicit context, the novice was enlightened.

The 'Only the Gods' one seems weird to me; maybe I just don't understand Git well enough, but it seems like that one's just a case of failing to understand what a branch <i>is</i>.<p>A particular commit isn't made 'on' a branch, so to speak; it's just a SHA hash that has a particular SHA as a parent. And then a branch is a pointer to a particular SHA. So there's no way to know which branch a commit originated 'on', merely which branches happen to contain a commit at present (because their current commit has the desired commit in its history).<p>So, if you merge two branches together, of course you can not tell which branch a given commit originated on just by looking at history. That information was never in the history in the first place.<p>I could see it being useful to track this in the merge somehow, though.

Sometimes I feel like Git is an elaborate troll by Torvalds. Doing my taxes is more intuitive.

Short of me downing distressing amounts of coffee, could someone explain these please for those of us still trying to grok git?

A lot of these are just plain wrong though or have a good reason and it makes me sad because I know Steve Losh uses a lot of Mercurial which I think has a much worse UI.<p>1. Silence: you can't alias built-in commands — for good reason. You don't change the defaults of commands, that's just going to cause problems with scripts. Why is it ignored silently? For starters because new git versions can add a command that would conflict with your config that came from an older version. You can trivially see that an alias is ignored by just adding ``--help`` to the command and it won't show you the alias.<p>2. One Thing Well: I fail to see the problem with that? All of these do the same thing. They check out a revision. With the exception of branch creation which is actually not a feature of `git checkout` but `git branch`. There is just a convenience operation on `git checkout` that also changes branches. The better question is why branches in mercurial are called bookmarks :P<p>3. Only the Gods: thankfully you don't know which branch something came from. Mercurial fucked me over more than once where I accidentally pulled a patch that came from a named branch that was conflicting with one I already had (you would not believe how many people name their branches "bugfix"). Mercurial's named branches are among the stupidest idea in software maintenance.<p>4. The Hobgoblin: these are all different commands. "How can I view a list of all tags": that's not what all tags is, that is "what's the list of tags I know locally". In mercurial you can't even figure that out properly because depending on the branch you're on you get different defined tags since tags are stored in the tree. Git's tag system is much superior to that.<p>"How can I view a list of all branches": that's a question you will never ask because it's the wrong question. A branch could show up multiple times. The correct question to ask is "How can I view a list of all local branches?" `git branch`, the second question is "how can I view a list of all remote branches?" And for that the answer is `git branch -r` or `git branch --remote` which makes a lot of sense in my mind.<p>"And how can I view the current branch": Same way you show all branches, just `git branch`. Shows you your current branch as well as all other branches and neatly colorizes it. `git rev-parse` is a command you really never have to use unless you script something.<p>Yeah, some could probably more consistent. The odd one out are `git submodule` and `git remote` which are sub commands instead of using parameters to remove/modify them. That being said, you rarely need to use those.<p>In direct comparison with hg, git's UI and functionality is a present from god. I'm pretty sure hg only has a better UI reputation because git's UI used to be pretty bad. Now however? Pretty sure it wins over hg hands down.

One Thing Well: The command of all these seemingly different action is the same, because all of these seemingly different actions are actually the same.<p>The Long and the Short of It: -h is not a valid argument. Passing -h therefore results in providing usage information.

Has anyone made an alternative interface for git that tidies this up without drastically changing how you use git? Or would this condemn someone's sanity to the graveyard?

I don't use a complicated .gitconfig (just user.name and user.email), so this is all new to me.<p>Something that leaps out to me as horribly wrong is that aliasing a builtin doesn't cause the config file to be "invalid". Doing anything else is just doing spooky things that are explained only several hundred lines into the man page by a single sentence.<p>Maybe better would be to choke on config lines that alias a builtin, and to print error messages before or after the output of each git command while the offending line(s) are present.<p>Further,<p><pre><code> git config alias.pull "pull --ff-only" </code></pre> should definitely be an error. Instead, git gladly makes the (no-op) confusing edit to your config file.

'git' alone tells me to 'git help &#60;command&#62;' for help, which I've done dutifully ever since. That is, until I too was enlightened a few minutes ago with 'git &#60;command&#62; -h'.<p>Thanks, Master Git!

Even if this was meant as an critique to Git, I (some kind of a Git-evangelist) enjoyed it a lot. I even learned something new!<p>The critique is quite well established. One needs to understand these quirks to be an enlightened Git user.<p>However we make up with them, as the overall gain from Git's approach to version control is so big.<p>Some things could be improved though, like introduce something like "git branch --current" to avoid the Hobgoblin...

I don't understood the suicidal git thing...<p>Also of course I had to test the help commands!<p>git branch --help opens man<p>git branch -h throws those short commandline help summaries.<p>Interestingly, -h does not mention -h itself or --help, so the only way to know that --help exists, is someone else telling you, you will never find on your own.

The best part of this article IMO is the scrolling header on the left hand. Nice touch.

I'm a relatively new git user. I'm rebasing a log when other developers commit unrelated changes. What is the problem with git rebase?