![[lang]](/images/eye.png)
ways in which git makes the opposite of sense to me |
2009-02-06
|
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:
- git adds the file 2 to the next commit
- 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.
> 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-02-07 @ 02:40
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-02-07 @ 04:27
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-02-07 @ 04:30
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:
http://kerneltrap.org/index.php?q=mailarchive/git/2009/1/22/4789314/thread
Comment by Rich — 2009-02-07 @ 09:09
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-02-07 @ 12:39
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-02-07 @ 12:43
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-02-07 @ 12:49
ack…why did it not show me that it went through the first time before hanging? :(
Comment by Ben Boeckel — 2009-02-07 @ 12:50
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
5
$ git –version
git version 1.6.1
Yes, it is true that
$ ls /usr/libexec/git-core | wc -l
138
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-02-07 @ 14:44
Arr, forgot to escape HTML
Exhibit G: It is “git checkout %lt;branch>†or (in modern git) “git checkout <file>“.
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-02-07 @ 14:54
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-02-07 @ 16:10
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-02-07 @ 16:36
hmm, comment system swallowed some punctuation in that last comment,
it should have read
“-h”
dash h
“–help”
dash dash help
in the GNU style
Comment by Alan — 2009-02-07 @ 16:55
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-02-07 @ 20:13
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
62
mathias@smarty:~$ ls /usr/bin/[^e]* | wc -l
4405
Comment by Mathias Hasselmann — 2009-02-07 @ 20:23
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-02-07 @ 23:06
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-02-08 @ 04:54
@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-02-08 @ 11:40
For what it’s worth, I did the exact same thing with “commit -a”.
Comment by Kevin — 2009-02-08 @ 13:21
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-02-08 @ 17:08
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-02-09 @ 06:41
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-02-09 @ 06:56
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-02-18 @ 23:25
[…] 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-02-24 @ 11:00
[…] thomas.apestaart.org » ways in which git makes the opposite of sense to me […]
Pingback by git monthly links: 2009-02 « git blog — 2009-03-01 @ 17:39
[…] (original article) […]
Pingback by Ways in which ‘Thomas’ appears the opposite of ’smart’ to me. « noah’s mark — 2009-03-05 @ 04:51