Present Perfect


Picture Gallery
Present Perfect

ways in which git makes the opposite of sense to me

Filed under: Hacking,Python,Twisted — Thomas @ 2:05 pm

2:05 pm

DISCLAIMER: I originally wrote this post 18 months ago but never posted it because it was unusually negative.

Recently, with GStreamer switching to git, and GNOME thinking of moving to it as well, I thought I’d pick the post back up and see if git had improved since writing it. For me, the most frustrating things about git are:

  • the user interface experience is the absolute worst of all of them since tla was around
  • there is no obvious way to do it – clearly shown by the 50 different git tutorials, and the myriads of git commands that are very similar-sounding and have strange descriptions that to the layman sound like they would do the same thing

Personally, I remain convinced that it would be easy to start a git hater’s blog (much like the linux hater’s one) and fill it with content, though I doubt that will stop me from using it in practice.

Feel free to rush to the defense of git, insult me, call me stupid, whatever you want! I just thought it’d be an interesting exercise to see if my frustrated vitriol from last time still held up.

I’ll annotate each part with today’s experience in italics, and finish off with a final git score.

Exhibit A:

[thomas@ana git]$ git init
Initialized empty Git repository in .git/
[thomas@ana git]$ mkdir t
[thomas@ana git]$ git add t
The following paths are ignored by one of your .gitignore files:
t (directory)
Use -f if you really want to add them.
[thomas@ana git]$ find . -name ".gitignore"

There is no .gitignore file, so what are you talking about ?

2009: this now actually works without problems. Score one for git! 1 out of 1 for git usability improvements.

Exhibit B:

[thomas@ana tmp]$ git clone gt clone
Initialized empty Git repository in /home/thomas/tmp/clone/.git/
fatal: 'gt': unable to chdir or not a git archive
fatal: The remote end hung up unexpectedly
fetch-pack from 'gt' failed.

Ok, so I have a typo. But this is how you choose to let me know ?
“unable to chdir” OR “not a git archive”. Hey, YOU’re the computer. And git, you’re the program tracking these things, you can’t tell the difference between a git archive and something that is not ? Why don’t YOU tell me which of the two it is instead of failing to handle errors in a logical way.

Also, I have no idea how it knew that I was on the phone with my mom and my mom got angry at something I said and ended the conversation. Oh ,wait, that wasn’t what you were referring to when talking about unexpected hangups ?

And I thought fatal meant fatal. Apparently the first fatal was not fatal enough to already stop, you prefer confusing me with another fatal. Which one of the two should I be fixing ?

Kudos though for cleaning up the failed creation of the clone repository.

Please, when I make this simple mistake, tell me only: “The repository ‘gt’ does not exist.”

2009: behaviour exactly the same. 1 out of 2 for git usability improvements.

Exhibit C:

[thomas@ana clone]$ ls /usr/bin/git-* | wc
139     139    3158

Compared with

[thomas@ana clone]$ ls /usr/bin/e* | wc
69      69    1244

I would say that the Lobby For Commands In /usr/bin Starting With G has gone a little overboard here.

2009: only 131 commands left for git. In the interest of preserving my sanity I’m not even going to try figure out which ones got removed or replaced or folded. 1 out of 3 for git usability improvements.

Exhibit D

Maybe that last one was an unfair stab ? Maybe 139 binaries come for free anyway so I should not complain ? I wasn’t sure either first. Until I took two random entries from there and ran:

[thomas@ana clone]$ git whatchanged -h
fatal: unrecognized argument: -h
[thomas@ana clone]$ git citool -h
usage: /usr/bin/git-citool
[thomas@ana clone]$

Care to guess how many of these binaries have no useful -h output ? I sure don’t want to find out, there’s 139 binaries to check. 130 of them have manpages though – I guess that could be one reason why git implements “git command” by having a binary “git-command” – how else are you going to document this monster ?

What I *really* wanted to do when finding this out is to find a command that would show me which files are not under version control and give that to me in the most easy to parse way. git status is something, but maybe one of those 138 other commands gives me something better ?

(answer after some random command ‘bisecting': git ls-files –others)

2009: behaviour has changed, but is still unhelpful

[thomas@ana git]$ git whatchanged -h
fatal: bad default revision 'HEAD'
[thomas@ana git]$ git citool -h

The last one now pops up a TK dialog box that says “couldn’t open /usr/share/git-gui/lib/tclIndex”: no such file or directory. 1 out of 4 for git usability improvements.

Exhibit E:

In my quest to figure out what some git commands do without wading through the man pages, I’ve resigned myself to the black box approach.

[thomas@ana clone]$ git describe
fatal: cannot describe '02d3a05f1e9710f9a6683ed8a62c9bd2ff3680a8'

For once I must side with git on this one. I have no way to describe that hex string either.

2009: output changed, but equally unhelpful:

fatal: Not a valid object name HEAD

Still inclined to side with git, I don’t name my objects HEAD either. 1 out of 5 for git usability improvements.

Exhibit F:
I’m following this simple tutorial and it suggests that git has a slightly different model for committing. Most VCS systems have you “add” paths to tell the VCS you want to track them. Git seems to have something in addition – it has “files that it tracks”, “files that it tracks and is going to commit in the next changeset”, and “files that it doesn’t track”. git add then seems to be used to add to “the next changeset”, and as a result also add it to “files that it tracks”. A little confusing, but OK. So basically, to do a commit, you must add files to the commit.

The tutorial explains that you can do both at once by using git commit -a. Obviously the two step process of committing was so unintuitive that they made an option do to both, and the tutorial thinks this shortcut is important enough to mention.

Except that this happens:

[thomas@ana git]$ touch 1
[thomas@ana git]$ git commit 1
error: pathspec '1' did not match any file(s) known to git.
Did you forget to 'git add'?
[thomas@ana git]$ git add 1
[thomas@ana git]$ git commit 1
Created commit 79e67c26b27c80f7f0ddc37293cbc022f932c968
 0 files changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 1
[thomas@ana git]$ touch 2
[thomas@ana git]$ git commit -a 2
Paths with -a does not make sense.
[thomas@ana git]$

I guess I should be lucky it didn’t call me stupid outright. It may not make sense to you, git, but I guess this is how my intuition works when I read your tutorial and you’ve already made it clear to me that you’re not planning to have your help or usage output to be helpful or useful or for that matter even be period.

As a hint, here’s what I expect to happen when I run git commit -a 2:

  1. git adds the file 2 to the next commit
  2. git commits the change to file 2

That wasn’t so hard to make sense of now, was it ?

2009: slightly different behaviour. First off, the actually helpful suggestion from before (did you forget to add 1) is now gone. Why ? The second part is still the same, exactly as is. 1 out of 6 for git usability improvements (and actually a step back).

Exhibit G:

[thomas@otto git]$ ls /home/thomas/tmp/git/repo/.git/
branches/    description  hooks/       objects/
config       HEAD         info/        refs/
[thomas@otto git]$ git checkout /home/thomas/tmp/git/repo
fatal: Not a git repository

What do you mean, not a git repository ? I gave you one argument that clearly is a repository. Could you try and tell me what is wrong in a way that us humans can read ?

2009: different error:

[thomas@ana git]$ git checkout /home/thomas/tmp/git
error: pathspec '' did not match any file(s) known to git.

I’m guessing I should be giving it an additional argument. Hey, wouldn’t that be a nice understandable error message instead ? 1 out of 7 for git usability improvements.

Exhibit H:

gitk is in Tk. Tk !!! 1991 called and they … Oh never mind, not even going there. No, really. Start it up and click on ‘File’. Then move the mouse pointer to ‘Edit’. Is it just me, expecting the logical thing to happen, while nothing happens at all ? At a guess, this behaviour was probably for those people who were logging in to a remote X server over a 300 baud modem.

2009: still the same. To be fair, the application is actually pretty useful, you’d almost forgive it being written in tk. Still, 1 out of 8 for git usability improvements.

If you’re still here, feel free to point out where git’s behaviour really was my fault. I’m all for learning more about why things are the way they are. I’m just not convinced at all yet that git has made huge inroads on the usability level as its defenders often claim when discussing git vs. bzr.


  1. On my system :

    ls /usr/bin/git-* | wc -l

    Git 1.6 actually fixed that, just FYI. And the git bash-completion module doesn’t show all 100+ git commands either. Hopefully, whatever distro you’re using will pick this new version up.

    Cheers :)

    Comment by Rémi Cardona — 2009-2-6 @ 2:28 pm

  2. We praise ourself of at least trying creating usable interfaces for real people in Gnome.
    Choosing git over bzr with that goal seems odd.

    Comment by anon — 2009-2-6 @ 2:30 pm

  3. Try –help instead of -h.

    Comment by Hongli Lai — 2009-2-6 @ 2:53 pm

  4. In Ubuntu jaunty some commands like “git-format-patch” went away in favor of “git format-patch”. So while there might be fewer binaries/scripts, the amount of commands _might_ still be the same (not sure).

    Comment by martin — 2009-2-6 @ 2:53 pm

  5. Ok, so you’ve run into some cases where if you’re doing weird/wrong stuff it gives you unhelpful error messages. Big deal. Who cares? What’s important is the actual workflow once you know how to use it. (I’m not saying these aren’t bugs or don’t need fixing, just that it all seems rather minor in the whole scheme of things).

    Also: since when do we care about usability with any of our tools? I mean *actually* care? Take autoconf/automake, configure, make, libtool, gcc, gettext, etc. – they’re all not exactly ‘user friendly’, but we still use them because they get the job done reasonably well once you know how to use them. (What do you use to write code? A fully integrated graphical IDE? Right, didn’t think so.). Not that usability isn’t a desirable goal, but we shouldn’t pretend it’s our prime concern on the tools side. Because it’s clearly not.

    If the tools we (as developers) choose to use are confusing to use for translators or artists, then we need to either solve stuff differently for those people (e.g. provide web-based access for them or somesuch), or start fixing the tools. (Newbie developers don’t count, the need to get a grip on the entire toolchain sooner or later anyway.)

    So, I presume you have submitted bugs for all these issues already?

    Comment by Tim — 2009-2-6 @ 2:55 pm

  6. I’m waiting for someone to write a wrapper tool for bzr/git/hg (and maybe even svn/cvs) all in one. Sort of like what packagekit does for apt/yum. Then I can just learn the interface of this generic VCS and of course it will be ported to all new VCS’s after git as well. Since the sole purpose of this generic interface would be to implement a persistent and usable interface for _humans_ I think it might turn out pretty nice.

    So dear lazyweb, when you can have this tool ready for me?

    Comment by martin — 2009-2-6 @ 2:55 pm

  7. Yeah, you are being unusually negative, possibly unusably.

    Git’s user interface and learning curve are still terrible.

    Fwiw, at least git –help command takes you to a man page for that command, and all of those have been good that I’ve used.

    For “Exibit F”, you make yourself look bad. I may be wrong, but the man page seems to explain it pretty well?
    -a will do a commit on all files, if that is the case, you shouldn’t use paths with it.

    Comment by dantealiegri — 2009-2-6 @ 2:59 pm

  8. Have you tried Mercurial? :)

    Comment by djc — 2009-2-6 @ 3:10 pm

  9. Hrmn, some of your problems are legitimate UI flaws… others seem to be you expecting git to be svn or cvs, and it definitely isn’t

    ‘git checkout’, for example. I think your misunderstanding there is that you expect ‘git clone’ to give you something like a local ‘svnroot’ that you’d then check out copies of. You mentioned a bunch of git tutorials… did you actually do any of them? :)

    I found http://www.sourcemage.org/Git_Guide to be really good.

    Comment by Jan Schmidt — 2009-2-6 @ 3:14 pm

  10. I just can’t agree more with you. That’s the reason I use bzr : I can recommand it for everybody a bit familiar with SVN or even to people new to DVCS. I can’t imagine doing the same with Git as I have myself too much difficulties to understand it.

    Comment by Ploum — 2009-2-6 @ 3:14 pm

  11. F. AFAIK, when using git commit -a, you don’t specify which files you will add and commit, you say you want to add and commit _all_ files that are not explicitly ignored (.gitignore)

    G. git checkout is for changing the current branch, not for checking out a repository (like in svn). Instead, what you’re looking for is:
    $ git clone #the first time you clone it
    $ git pull #after the first step, when you want to pull updates

    So the argument it is looking for is actually the name of the branch you want to switch to.

    H. try qgit instead ;)

    About the other complains on error and help messages, I can only agree with you. But I’m sure the git devs would love to have bugs filed.

    Let’s hope you won’t be too much handicaped by the switch to git by the projects you work on.

    Comment by bochecha — 2009-2-6 @ 3:18 pm

  12. Tim: git doesn’t have a bug tracker, they prefer the kernel-style “post patches to the mailing list” development style.

    Comment by James — 2009-2-6 @ 3:24 pm

  13. It’s wrong to expect anything from git. It’s a cli tool, not KidPix, so you’d have to ask yourself “What can I do with this tool, how do I do it, and where to start?” You seem to make up your own opinions beforehand and randomly throw them at git. Hardly git’s fault.

    Also, the way git usability improves it actually mostly the following:
    Someone writes to the git mailing list, says
    1. I did this
    2. I expected this

    Now discussion ensues if and how to enhance the usability. However, 1. has to start somewhere around “I and git want to achieve this” not “git does’t help me if I tell it -helpme. Git is missing my favorite pink syntax color” (Hint: Git help is available through the command “git help”, “git help command” (or also “git command –help”).

    Comment by ulrik — 2009-2-6 @ 3:25 pm

  14. you made me laugh. really. The best part was either
    a) the complaint that telling git to add all files to the index and commit them (git commit -a) and adding a path to the command yielded an error (what would you do, if your mum calls and says: bring all food to my party the cookies?


    b) wondering that git checkout could not do anything as was obviously not in the repo you worked on.

    If that wasn’t a joke at all, please consider:
    a) reading manpages
    b) thinking again about what is an DVCS

    Comment by choeger — 2009-2-6 @ 3:32 pm

  15. Why is there git clone and git pull anyway?

    git pull in both ways (at first with a path to the origin given) would do the job just fine.

    afterwards git pull pulls from the first location…

    Comment by mike — 2009-2-6 @ 3:34 pm

  16. Mercurial and bzr users can only smile seeing this. It’s even funny the proliferation of git tips and tricks websites. I just only speaks about the usability disaster git is.
    Have you tried Mercurial?

    Comment by pachi — 2009-2-6 @ 3:38 pm

  17. are you crazy?

    Comment by bummer — 2009-2-6 @ 3:50 pm

  18. As Gnome and GStreamer are completely bug free, it’s fair for you to criticize minor UI bugs with git.

    $ gnome-terminal -h
    Unknown option -h
    Run ‘gnome-terminal –help’ to see a full list of available command line options.

    $ gnome-open -h
    Error showing url: The location or file could not be found.


    Comment by Richard — 2009-2-6 @ 3:57 pm

  19. I just switched from SVN to git at work and I must say that git is a breath of fresh air. I think once you grasp the basic concepts, everything else makes sense and you can easily deal with the error messages. It took me an afternoon to do that part.

    I do agree that the error messages are less than helpful. But on the scale of things, that’s not really a big deal once you know how to use it. And all the commands have decent man pages, often with examples and certainly with explanation about the concepts in addition to just listing arguments and flags. And you can do it just like you would with svn: git help foo.

    Comment by Joel — 2009-2-6 @ 4:00 pm

  20. To Rémi Cardona who says git “fixed” the tons of binaries confusion.

    ls /usr/lib/git-core |wc -l

    Ok. So.. there are more now, they are just hidden in /usr/lib/git-core. Awesome.

    Comment by codemac — 2009-2-6 @ 4:44 pm

  21. $ ls -h
    Desktop Documents …

    Duh, ls is broken! :-D (actually the -h switch is for printing human readable file sizes)

    $ rm -fr / somecrap

    Whoa, rm is even more broken, it doesn’t read my mind! :-D :-p

    Regarding “git add”: Probably my brain is broken, but for me git is the first tool getting this part right.

    IMHO a SCM tool really should just commit the changes you want to commit, not every random stuff you touched in the same work session. The git developers share that opinion and prominently show that decision. They even allow alternate workflow (git commit -a) and they even allow more fine grained content tracking (note, not “file tracking”) via “git add –patch”.

    Maybe other people are more focused than me or they care less about broken details, in 50% of my work sessions it happens, that I see some additional problem that needs attention and I fix it right when seeing this. With other tools but git I always had trouble to commit unrelated changes separately. Most of the time I’ve commited some inconsistent state. At least for me “git add” is extremly helpful.

    Comment by Mathias Hasselmann — 2009-2-6 @ 4:59 pm

  22. Forgot to mention: For browsing git repositories giggle is quite useful already (http://live.gnome.org/giggle), even if it still has quite some way to go: http://bugzilla.gnome.org/buglist.cgi?query=product:giggle

    Comment by Mathias Hasselmann — 2009-2-6 @ 5:11 pm

  23. So, how about submitting some suggestions for better error messages? I’ll give you 18 months before I check back and see how you’re doing.

    Comment by foo — 2009-2-6 @ 5:29 pm

  24. Richard, you forgot

    $ gst-codec-info-0.10 -h
    W: ‘-h’ is no valid plugin filename

    $ gst-inspect-0.10 -h
    Error initializing: Unknown option -h


    Comment by jmj — 2009-2-6 @ 5:36 pm

  25. Maybe git could just go all out and intentionally offend the user so that git fanatics wouldn’t have to do it themselves.

    Comment by Murray Cumming — 2009-2-6 @ 5:39 pm

  26. Your criticism of tk is misplaced – it got a graphical overhaul a while back – if your gitk doesn’t, say, have antialiased fonts, you’re probably running a shitty old tk. If you’re running recent tk, gitk looks fine.

    Comment by tkspork — 2009-2-6 @ 6:21 pm

  27. Re F: Not quite true.

    git has the tree in current commit (HEAD), the tree that will become the next commit (the index), and files it pretends doesn’t exist (.gitignore). git add takes the /current/ copy of the file and puts it in the index. git commit takes the index and writes it to the repo. You can think of the index as an in-memory buffer on a file. First you put data there, then you write the buffer to disk.

    This is slightly different from your description in that, if you add a file and then modify it, the previous version of the file goes to the index. If you prefer, one of the newer git versions has an alias git stage instead of git add, which describes its purpose better. (Similar a new git diff –staged alias for git diff –cached.)

    Since a common operation (especially for people coming from SVN) is to take all your current changes and stuff them into a commit, git commit has a -a flag which first runs git add on all the files it knows about (i.e. everything in the current index) before git commit. You usually don’t want to be specifying files as git commit arguments. (You can… git is relatively workflow-agnostic, but I recommend against it so you have a stopping point to run git diff –staged and other checks when you need to. I also find it “feels better” with respect to the “never say ‘you should have'” setup in git.)

    This separate staging area, while an extra step in the SVN workflow (though -a mostly emulates the old SVN behavior) allows for things that are simply not possible in other VCSs. It means that your commit have to be dumps of your working tree. It means your messy coding habits are not forced to reflect the clean-looking history. It means your clean-looking history needn’t be affected by your messy coding habits. It becomes very easy to split changes into multiple commits and (with the help of git rebase -i and git add -p) refactor history. It becomes very easy to split your commits into separate, logically-distinct chunks, and allows for the very natural workflow of work on stuff, making commits to save data, then rewrite the history to make it presentable. You don’t want others to know and others don’t care that you had to try four times before that file compiled, and you should not have to push off making commits (and save up for one big commit) just to mask this. Local history is just as useful as upstream history and should be maintained.


    Comment by David — 2009-2-6 @ 6:26 pm

  28. Once you grokked the concept of git (and DVCS in general) and learned about how to use it (reading the manpages to know how to use the commands correctly would be a good way to start), git offers an incredible fertile workflow. Especially branching and merging is more comfortable and easy to use compared to bzr and hg IMO. Just my 2☠

    Comment by buz — 2009-2-6 @ 6:34 pm

  29. > As a hint, here’s what I expect to happen when I run git commit -a 2:
    > 1. git adds the file 2 to the next commit
    > 2. git commits the change to file 2

    Where did you get that idea? It’s not supposed to do anything of the sort and the meaning of the -a option is the first thing that is explained in the man page.

    Comment by Mike — 2009-2-6 @ 7:02 pm

  30. Thanks for the laugh :)

    B. Stop being an idiot. “git” can’t read your mind, and I’m not sure it would want to. Might end up starving.
    C. In current versions, they’ve replaced all the “git-” with using “git ” + the command. Also, you should try taking the wc of commands that start with “k” and “g” (minus git), and see how many of those there are.
    D. “git help ” or “git cmdname –help” or “man git-” or google “git “. Ironically, the only other command you seem to understand, “ls”, also “fails” at having help output triggered by “-h”. Good work!
    E. “git describe” tells you the nearest tag reachable from a given commit (or HEAD, by default). If you don’t have any tags, then it can’t describe them. What were you expecting this to do? Also, if you “resign yourself to the black box approach” just because “-h” doesn’t work, then you should probably quit now, or at least discover the googles. Seriously.
    F. In current versions of git, you can just say “git commit “, and it skips the staging area and commits the file(s). “-a” can’t be combined with filespecs, which is exactly what it was telling you.
    G. I don’t think that word means what you think it means. “checkout” is meant to be invoked, /from an existing repo/, and checks out a branch or path into that repo. You used “git clone” (badly) in Exhibit B; did you forget about that by the time you got around to Exhibit G?

    Anyways, good work! And thanks for inviting us to insult you – rookie mistake, bubba.

    Comment by Noah — 2009-2-6 @ 7:12 pm

  31. …cute, your comment thing swallowed all my angle brackets. Brilliant. In case it wasn’t clear:

    D. “git help [cmdname]” or “git [cmdname] –help” or “man git-[cmdname]” or google “git [cmdname]“. Ironically, the only other command you seem to understand, “ls”, also “fails” at having help output triggered by “-h”. Good work!

    Comment by Noah — 2009-2-6 @ 7:14 pm

  32. > For once I must side with git on this one. I have no way to describe that hex string either.

    best laugh i’ve had all day :)

    Comment by Martin DeMello — 2009-2-6 @ 7:28 pm

  33. $ svn checkout master
    svn: Try ‘svn help’ for more info
    svn: Error parsing arguments

    Piece of crap.

    Comment by Russ — 2009-2-6 @ 7:42 pm

  34. What we have here is a refusal to try to work with a new tool due to some personal bias. Seriously, how difficult is it to type git checkout –help to figure out what is going on?

    Comment by Russ — 2009-2-6 @ 7:44 pm

  35. General comments:
    Your claim of the 2009 variants being worse is only because the repository you were in when you tried it again did not contain a single commit (ergo the message “fatal: Not a valid object name HEAD”). Maybe a special-case error message should be added for that.

    Exhibit G:
    You want clone, not checkout.
    # git checkout -h
    usage: git checkout [options]
    or: git checkout [options] [] — …

    # git clone -h
    usage: git clone [options] [--] []

    So you passed a path to a repo, rather than a branch. The error message ‘Not a git repository’ might be better worded as ‘not presently in a git repository’.

    Exhibit F:
    The short help might be better updated to read:
    # git add (options) -a
    # git add (options) (–) filenames
    to indicate that filenames and -a cannot be mixed.

    Exhibit E:
    Your original output was correct. “Describe” is only useful once you have tags in your repository. Maybe a special-case error message, “no tags to use for describe”.

    Exhibit D:
    Blame your distro for not installing citool/Tcl properly. Tcl’s auto_mkindex was not invoked, so the Tcl stuff is failing to run.

    Exhibit C:
    Why is many commands a bad thing?
    CVS has 32.
    SVN has 33.
    Bzr has 61.
    Hg has 63 (hg -v –help).
    I don’t know about bzr and Hg, but for both CVS and SVN, many of the commands are heavily overloaded with different sets of conflicting options, while Git has tried very hard to not overload commands. CVS ‘admin’ is very badly overloaded. SVN got better with less overloading, mostly only having two or three modes of overloading (changelist, diff, merge, switch off the top of my head).

    Comment by robbat2 — 2009-2-6 @ 7:48 pm

  36. Ah crap, your comment system ate some of my text.
    Here’s the corrected version:
    usage: git checkout [options] <branch>
    or: git checkout [options] [<branch>] — <file>…

    # git clone -h
    usage: git clone [options] [--] <repo> [<dir>]

    Comment by robbat2 — 2009-2-6 @ 7:51 pm

  37. your blog title is ‘present perfect’… and it describes a past far gone.

    Comment by baczek — 2009-2-6 @ 8:04 pm

  38. Re 15:

    git clone is a shorthand for: git init; git remote add origin URI; git fetch; git merge origin/master
    git pull is a shorthand for: git fetch; git merge origin/master

    Both are not strictly necessary, but save typing.

    Comment by anon — 2009-2-6 @ 8:08 pm

  39. The DVCS war seems to make intelligent software developers retarded when they use a DVCS tool which is not their beloved one. Or at least so it seems from the surface. I think it’s really about rhetorics, though.

    But this trick won’t work very long because the open-source world is adopting Git pretty quickly and I think it is already showing that normal people can learn and use it easily.

    Comment by Radiophonic — 2009-2-6 @ 8:39 pm

  40. @Richard: Yeah, GNOME primary concern are of course Terminal-UIs..


    Comment by bla — 2009-2-6 @ 9:03 pm

  41. Forget about giggle ;) Here comes gitg!

    Comment by Jesse van den Kieboom — 2009-2-6 @ 10:29 pm

  42. What would you think of a GStreamer user that instead of following the recommended way to bring up issues to the community makes a blog post and dumps all of his criticism without any suggestions: not very productive.

    Fortunately git’s way is much easier than GStreamer’s; just copy/paste your blog post to the git mailing list, I’m sure all your issues would be addressed and some even fixed.

    And of course, like GStreamer, it’s an open source project, so patches are welcome.

    Also, gitk works just fine, and in fact it’s much more responsive than most GTK+ applications. If you don’t like it you can develop your own, or contribute to an existing tool (gitg).

    As an experienced git user I would say yours are not important issues, a bit of reading, for example ‘git from the bottom up’ will probably make you understand how wrong you are in many of the things you are trying, which might be valid issues for extreme newbies, which should of course bring up these issues in proper ways or they will never be fixed.

    But of course your objective is not to improve git, but to bitch about it.

    Comment by Felipe Contreras — 2009-2-6 @ 10:39 pm

  43. No way dude are you serious?


    Comment by Jenkins — 2009-2-6 @ 11:54 pm

  44. There is a long tradition of accepting tools that provide only the simplest of features before a steep learning curve is encountered. This is doubly true in the unix world (vim, emacs, bash, …). Until a few years ago, expecting to use linux on most or all of your hardware without going through a manual kernel compile procedure was unreasonable. It seems like it shouldn’t be such a surprise that a version control written in the same spirit might gain popularity.

    Git isn’t the friendliest to new users, but so long as a project has one experienced git user around, they can pretty much get anyone else out of trouble. And once you understand the basics, trouble in git isn’t nearly as bad as trouble in svn. Back when I used svn day to day, having to un-fuck the working copy by re-checking-out was at least a monthly occurrence. Using diff/patch to manually preserve some changes was nearly a daily occurrence. With git, I’ve carried the same working copy with me across eight months and and three windows installs I can’t remember the last time I used diff/patch to work around a VCS shortcoming.

    Comment by Brian — 2009-2-7 @ 12:09 am

  45. You’ve just shown the internet how dense you are. Congrats. Learn how to use man pages.

    [thomas@otto git]$ git checkout /home/thomas/tmp/git/repo
    fatal: Not a git repository

    That’s not what “git checkout” is for. You’re used to interfaces for other VCSs, so obviously this should “checkout” the repository at said directory. But that’s not what “checkout” is for: “checkout” changes the *current directory* to the branch that you are “checking out.” Now, it’s forgivable that you might not know this. But do you really expect git to read your mind and figure out that you are using the command completely incorrectly?? It’s like if you typed “scp myfiles /home/thomas/@remoteserver”. SCP doesn’t even tell you that you just copied your files to a file named @remoteserve in your home directory!! APPALLING INTERFACE!! DWIM!

    Read the manpage for git-checkout, and it would be instantly clear to you that it expects the name of a branch and works from within your repository. Read any of the online tutorials and it becomes clear that you use git-checkout to switch to a named branch within the git system.

    Comment by Stephen — 2009-2-7 @ 12:12 am

  46. Dude, read the man pages carefully. There is no spoon (feeding).

    Comment by Alok — 2009-2-7 @ 12:52 am

  47. When programming, do you also try random C statements and hope the code’ll do want you want? And then complain about error messages produced by gcc, which of course you invoke with random options?

    Comment by anon — 2009-2-7 @ 1:20 am


    It amazes me how any blog post that criticises Git turns alleged grown ups into squealing babies.

    Perhaps its some form of stockholm syndrome?

    Comment by John Carr — 2009-2-7 @ 1:32 am

  49. I was going to comment but I figure you’ve suffered enough.. at about comment 20 I start feeling a little sorry for you, by 40 I was trying to think of nice things to say. 18 months ago you made a good decision is about the best I could come up with … seriously though, you should at least using git, you light like it

    Comment by Tim Parkin — 2009-2-7 @ 1:36 am

  50. Error messages must make sense to a human, there is nothing negative about asking that.

    Comment by Aigars Mahinovs — 2009-2-7 @ 1:55 am

  51. > Error messages must make sense to a human, there is nothing negative about asking that.

    You can’t expect someone to use a CLI command for the wrong purpose and expect a human-understandable error message. What if you thought “cp” meant “create pipe”? `cp pipe1 pipe2` will just say “cp: cannot stat `pipe1′: No such file or directory”. There are some cases where you can tell a person how to use the command, but you can only expect so much if they’re using it for the completely wrong purpose.

    Comment by Stephen — 2009-2-7 @ 2:40 am

  52. I don’t know about Exhibit F being a problem. Sure, it’s a little confusing at first, but when you get the hang of it, I think that it is one of the most useful features of Git. If you don’t like it, just do a ‘git add’ on the files you want, and then ‘git commit -a’ to commit all changed files. Easy.

    As for H, you should take a look at Imendio’s Giggle tool, which is really great – http://live.gnome.org/giggle

    Comment by Stephen Gentle — 2009-2-7 @ 4:27 am

  53. Use EasyGit, that’s what I do. It behaves far more sanely and has –help for everything.

    git is a source control system backend, not a source control system.

    Comment by Havoc — 2009-2-7 @ 4:30 am

  54. My least favorite git fact is that you cannot clone an empty repository. Why? There is no why.

    I ranted about it to the git developers here:


    Comment by Rich — 2009-2-7 @ 9:09 am

  55. Thomas –

    While I agree with some of your points about git flaws (particularly those about providing useful help and error messages), many of the others are just terrible. You’re seemingly running commands at random, and complaining they don’t do what you’d expect. Instead, spend an hour or so to learn the basics of the tool – I assure you, that’s all it takes – and then actually apply some intelligence to your critique. Then people might pay heed to the valid points you’ve raised.

    As it stands, I think this post only makes you look foolish, ranting about something you don’t understand.

    Comment by Simon — 2009-2-7 @ 12:39 pm

  56. As other have mentioned, errors can be terse, but git help goes a long way. I have just submitted git-cola for updates-testing if you want to grab that (it uses PyQt4). Be sure to grab the optional python-inotify so that you’re not left mashing Ctrl+R to update its view. It offers a very nice interface for doing everything (such as separating the index, modified files, and untracked files from each other). You’ll still need a repo viewer such as qgit and git-cola can work with any of them. git-cola supports more than gitk or any other GUI for git (according to the one table of features I found), so you’re not left without one for commands such as bisect or cherry-pick.

    Comment by Ben Boeckel — 2009-2-7 @ 12:43 pm

  57. As others have mentioned, git help goes a long way. You may be interested in a package I have just submitted to Fedora recently (in Rawhide and headed for updates-testing soon). It’s called git-cola and it provides a nice PyQt4 interface to interact with a git repository. You’ll probably also want to grab python-inotify so you don’t have to have it scan for updates to files manually. It offers a very nice interface for doing everything with a git repository (such as visually separating the index, modified files, and untracked files from each other). You’ll probably still want to get a repository viewer such as qgit (git-cola can work with any however). According to some feature matrix I found (I think it was on the git wiki), it supports more commands than any other GUI tool (even gitk). You won’t be missing cherry-pibk or bisect with it.

    Comment by Ben Boeckel — 2009-2-7 @ 12:49 pm

  58. ack…why did it not show me that it went through the first time before hanging? :(

    Comment by Ben Boeckel — 2009-2-7 @ 12:50 pm

  59. Suggestion: if you don’t like git UI, try EasyGit (eg) from newren (http://www.gnome.org/~newren/eg/) which is alternate UI for git.

    About git GUI worst since tla… tla/GNU Arch GUI from what I have read (from its documentation and in Eric S. Raymond draft of “Undersnading Version Control” paper) was much, much worse. Especially that git GUI got improved since times when it was “usable by Linus only” ;-)

    About 50 git tutorials and HOWTOs: how about starting with distributed together with git “Git User’s Manual”?

    Exhibit C:

    $ ls /usr/bin/git-* | wc -l
    $ git –version
    git version 1.6.1

    Yes, it is true that

    $ ls /usr/libexec/git-core | wc -l

    but what do you care? Beside, take a look for example at

    $ ls -l /usr/libexec/git-core/git-add
    -rwxr-xr-x 91 root root 868696 Jan 15 17:55 /usr/libexec/git-core/git-add

    Most of those 138 files (around 90 of them) are hardlinks to ‘git’. They are here for historical reasons (for use in scripts, and because dashed form was used in scripts), and because some people prefer using dashed form (“git-add” instead of “git add”). And most of them are meant for scripting use. There are about 37 commands that are meant for end user, and about 20-25 one usually use.

    Exhibit B: Your complaint is partially fair. git-clone “leaks” error message from actions (commands) it invokes, and that could get improved. “The remote end hung up unexpectedly” is from the transport layer.

    Your complaint is partially wrong, first because you should have read “Git User’s Guide”, or git-clone manpage that the syntax is “git clone “, where might be URL, and might be path to other git repository. Second because git cannot know if it is truly not a git repository, or do you simply not have permissions to enter given directory.

    Exhibit D: it is ‘–help’, not ‘-h’. And this complaint is not limited to git, isn’t it?

    Exhibit E: the situation changed, that is why output changed. “git describe” is shortcut for “git describe HEAD”, that is why HEAD appears in second error message. But I agree that error messages might be less cryptic for uninitiated.

    Exhibit F: “Paths with -a does not make sense.” because ‘-a’ / ‘–all’ means to commit all known to git changed files, so it does not make sense together with path; the path is always redundant. Also like in every SCM you have to “git add” unknown (new) files; you can only commit ‘known’ files.

    Exhibit G: “git checkout ” or (in modern git) “git checkout “. And you have to be inside git repository, and you were not: you should be in ‘repo’ directory (or subdirectory of it), and you were in ‘git’ directory (which probably wasn’t under version control, i.e. it didn’t have ‘.git’ directory in it).

    In second situation you were in git repository (duh! try to do the same!), but you supplied incorrect arguments: path to repository, which git interpreted as “git checkout “… and of course absolute path was to file which was not under version control (was repository itself).

    You were stupid, and you didn’t RTFM. ;-)

    Exhibit H: gitk is in Tk. Tk is portable. If you don’t like Tk, there is QGit, there is Giggle… there is tig if you like ncurses…

    Comment by Jakub Narębski — 2009-2-7 @ 2:44 pm

  60. Arr, forgot to escape HTML

    Exhibit G: It is “git checkout %lt;branch>” or (in modern git) “git checkout &ltfile>“.

    In first case (“fatal: Not a git repository”) you have to be inside git repository, and you were not: you should be in ‘repo’ directory (or subdirectory of it), and you were in ‘git’ directory (which probably wasn’t under version control, i.e. it didn’t have ‘.git’ directory in it).

    In second situation you were in git repository (duh! try to do the same!), but you supplied incorrect arguments: path to repository, which git interpreted as “git checkout <file>“… and of course absolute path was to file which was not under version control (was repository itself).

    You were stupid, and you didn’t RTFM. ;-)

    Comment by Jakub Narębski — 2009-2-7 @ 2:54 pm

  61. A: Fixed.

    B: The error message is unambiguous, if somewhat verbose.

    C: There are 36 commands in the list of high-level commands in git’s man page. Complaining about the rest is like complaining that bzr’s python API has too many methods.

    D: Omg, you found two commands without a -h. Please file a bug report. In my personal usage, i have yet to stumble upon a command without a good –help.

    E: –help.

    F: –help. Look what -a is supposed to do instead of complaining it fails to add air to your bike tires.

    G: –help. Look at what checkout is supposed to do instead of complainint it fails to increase your LCD’s physical resolution.

    H: Tk isn’t even bad-looking. Much nicer than the skinned horrors in some applications.

    Comment by ion — 2009-2-7 @ 4:10 pm

  62. I’m surprised at all the criticism Thomas is getting here. It is entirely reasonable to expect good feedback and usability, even from a command line interfaces. I’m quite surprised that -h and –help didn’t work. Suggestions to “read the manual” seem a bit presumptive about the quality of the documentation and even then it can be very hard to know where to start and what to read. It is a truism to say “it’s easy when you know how” and a lot of the comments amount to that. The barbed comments about gstreamer are amusing but only reinforce the criticisms of git. If this is the level of criticism Thomas is getting when he expresses difficulties with git I dread to think what translators and casual infrequent contributors will have to put up with.

    The usual tired suggestions to file bug reports are predictable (the command line error handling just seems poor overall) but I assume Thomas isn’t looking to become a git hacker, and his blog is a perfectly good place to discuss difficulties he as a Gnome developer had using git if Gnome is moving to Git. It will probably be appropriate to also repost some of comments when a relevant discussion comes up on a mailing list but it is very presumptive to complain about Thomas gathering his thoughts in a journal entry, a draft he put aside months ago and revisited giving his considered opinion.

    Thanks for writing. Interesting to see an engaged but skeptical opinion.

    Comment by Alan — 2009-2-7 @ 4:36 pm

  63. hmm, comment system swallowed some punctuation in that last comment,
    it should have read
    dash h
    dash dash help
    in the GNU style

    Comment by Alan — 2009-2-7 @ 4:55 pm

  64. Alan: There’s no bug tracker for git, just email. What’s so difficult about sending an email? I bet it would have been easier than writing this blog post.

    Comment by Felipe Contreras — 2009-2-7 @ 8:13 pm

  65. Alan: Actually all git commands support the “–help” switch. What they usually don’t support is some “-h”, and this is not different from most other tools on some GNU system.

    Thomas: Just realized that whilest “e” is the most common letter in English, there are only few words and commands that actually start with that letter:

    mathias@smarty:~$ ls /usr/bin/e* | wc -l
    mathias@smarty:~$ ls /usr/bin/[^e]* | wc -l

    Comment by Mathias Hasselmann — 2009-2-7 @ 8:23 pm

  66. I find it quite ironic someone calling TK 1991, when they use the gtk toolkit. One of the ugliest of them all. Using it makes opposite of sense to me.

    I’m also not completely sold on git myself though, so I do agree it needs large amounts of polish. Have you tried giggle or qgit? No library, makes creating a gui a bit of a pain.

    Comment by silv — 2009-2-7 @ 11:06 pm

  67. It looks like most of the errors you’re encountering are because you don’t have any commits in your repository. Git doesn’t give a useful error message about that. I’m not sure why. But, a lot of those bizarre errors you got are because of that. Even your clone error is extra bizarre because there’s no valid HEAD. The “could not describe HEXSTRING” error was for the same reason.

    I agree with an earlier post in that you should frame this sort of thing in an “I did this, expected that, and got yonder” manner.

    Git obviously needs to be a bit smarter about not-quite-totally-initialized repositories. I know that the reason it doesn’t create such a repository is so you can have the initial commit be an existing set of data, or so that you can rebase your history correctly.

    Comment by John — 2009-2-8 @ 4:54 am

  68. @Alan – Thomas is getting (and deserving) criticism because he’s doing a very poor job of arguing his case, starting with his comments about starting a git-haters blog. If his objective is to point out issues with git, he’s wrapped it up in too much sarcasm, ranting, and seeming ignorance for it to actually serve that objective.

    Comment by Simon — 2009-2-8 @ 11:40 am

  69. For what it’s worth, I did the exact same thing with “commit -a”.

    Comment by Kevin — 2009-2-8 @ 1:21 pm

  70. Git core is really nice, cool and powerful.

    But UI needs redoing from scratch (I prefer svn and/or hg)

    Agree about Tk.

    Comment by Mark — 2009-2-8 @ 5:08 pm

  71. Actually Exhibit F is the tutorial’s fault not git’s

    in git commit -a the -a means all if you want to give it a list of things to commit just do
    git commit [stuff]

    git commit -a is ‘commit all tracked files that have changed’ so git is correct in saying that paths don’t make sense when it is given

    so really git commit can function as ‘commit the stuff I added’ when run with no arguments, or ‘add and commit these files’ when you git a list of stuff or it can do ‘commit all the tracked files with changes’ if you give it -a

    Comment by Spudd86 — 2009-2-9 @ 6:41 am

  72. Also most of those 139 commands are not meant to be used directly by human users, but exist for scripting git and for other parts of git to call out to

    Comment by Spudd86 — 2009-2-9 @ 6:56 am

  73. For the record, I’ve sent a series of patches that make ‘git config’ more user friendly, and now I’ve learned about parseopt, which is a utility that was introduced at some point in git. It makes the usage output look much nicer, and -h works with that.

    Not all the UI has migrated to to parseopt, but eventually it might happen, if people send patches for that.

    Comment by Felipe Contreras — 2009-2-18 @ 11:25 pm

  74. [...] mean the interface has to suck: ways in which git makes the opposite of sense.   posted by glyphobet     reddit_url=’http://glyphobet.net/blog/blurb/334′ [...]

    Pingback by Just because it’s a command line tool… - glyphobet • глыфобет • γλυφοβετ — 2009-2-24 @ 11:00 am

  75. [...] thomas.apestaart.org » ways in which git makes the opposite of sense to me [...]

    Pingback by git monthly links: 2009-02 « git blog — 2009-3-1 @ 5:39 pm

  76. [...] (original article) [...]

    Pingback by Ways in which ‘Thomas’ appears the opposite of ’smart’ to me. « noah’s mark — 2009-3-5 @ 4:51 am

RSS feed for comments on this post. TrackBack URL

Leave a comment