Now as anyone who knows me knows, I love Git. I find it gives a very productive and comfortable workflow. One of my favourite new(ish) features is git rebase --interactive, which along with cheap’n'fast branching gives a great way to hack and commit as you go and then later on refactor your work into sets of nice orthogonal patches.
However, there I do still find a good few things wrong with git, so I’d like to discuss these problems and possible solutions:
- Error Messages
In general git has some terrible cryptic error messages. My favourite example is if you modify a file and then pull a change that modifies that file before you commit it:
Updating beb8c37..b953e6f
test: needs update
fatal: Entry 'test' not uptodate. Cannot merge.WTF? what does uptodate mean? why isn’t it up to date? whats gone wrong? what should i do?
Surely something like:Cancelling pull as 'test' has changes that would be overwritten by this pull. Please commit your changes or force an overwrite using the '--force' flagwould be a lot better?
I leave it as a reader excercise to repeat this process for most error messages…
- The index
Why oh why oh why is it called the index? It does no indexing as far as the user is concerned. Its name gives you no clue to what it is, you don’t know when or how you’re supposed to use it.
git addandgit rmmodify it and it’s used all over the place by the obscure low-level git helpers that you stumble over.How about commit staging area, that being what it actually is. You could have nice commands like
git stageandgit unstageandgit stage --interactive. That’d make more sense, right? Thengit addandgit rmwould be a lot more meaningful, being only used when you actually want add or remove a file. - Remotes
With
git remotethis is a lot better than it used to be – having to use cryptic refspecs (seegit-pullmanpage for the gory details). Unfortunately refspecs are still scattered all over the documentation just to confuse you… That should almost certainly be moved out to less user-visible documentation.The main issues I have now are:
- Remote branches don’t always behave like local branches when they should. In particular
git pull . <remote branch name>doesn’t work (and gives an obscure error) butgit merge <remote branch name>does. remote branches should act just like local branches you can’t modify. - I’m not sure I like
git branch -rto list remote branches, maybegit remote brancheswould be nicer and more obvious, or evengit branch --remote
- Remote branches don’t always behave like local branches when they should. In particular
- Lots of
git-*commands that confuse peopleThis is a common complaint, and I have to say that I agree. Why not put all the low-level commands in libexec? People who really use them often (which can’t be many!) can always add it to their path.
- No bug tracker!
For such a user-facing tool, a bug tracker would be very useful for users who lack the experience or time to get their hands dirty in the codebase. It certainly seems that just taking bugs to the mailinglist without a patch isn’t generally useful.
So, what do people think? What other bugbears do beginners and experienced git users see? Are these useful ideas?
After some discussion, I’ll happily take these to the git mailing list and come up with some patches!
Update:
Looks like people had some problems with my OpenID based login. Comments are now open.
I’ll agree with everything you say except for #4. I always enjoyed having all the git- tools right there and being in my path. Easy to tab complete. I also thought it made learning git easier. I was not always loading up a man page figure something out. Seemed commands were right there at my finger tips. I would hit git-. Oh, pull that probably does what I want.
2. This has been discussed on git mailing list, please search the archive
4. Bug your distro maintainer. Setting gitexecdir in config.mak should work
As for the rest, yes I’d like to see discussions on git mailing list
Regarding item 1: I agree. Git 1.5 improved numerous messages, but more need improving. This gets better all the time. If you see a specific message that should become clearer, report it upstream (ideally with a patch, as message changes require very little work), or report it to Debian.
Regarding item 2: actually, Git started out that way. While it always went by the name “index”, at one point you had to use separate commands to update it, such as “git update-index” rather than “git add”. This changed with Git 1.5, for the better. Now you can universally say that “git add” adds content, whether a new file or new contents for an existing file. I do agree that “commit staging area” makes more sense, though.
Regarding item 3.1: you should use git merge for all branches, local or remote. “git pull . branchname” makes less sense as a means to invoke a merge operation, and no longer works for remote branches. (Honestly, I’ve stopped using pull altogether; I fetch, and then either merge or rebase after glancing over the changes.)
Regarding item 3.2: sure, those alternatives make sense, so how about proposing them as alternatives? “git remote branches remotename” makes sense, “git remote branches” with no remote to show all branches makes sense, and “git branch –remote” makes sense as the long form of “git branch -r”.
Regarding item 4: how do you know that most people don’t use the “low-level commands”? What do you define as “low-level commands”? Quite frequently, a new command comes along that makes other commands “low-level” by providing a more user-friendly, high-level alternative. Should the old commands immediately move to libexec? What about scripts that people wrote; they will almost always need to add libexec to the PATH, because they should almost always use the “low-level” commands. That said, I do agree that some commands almost universally don’t need to remain in the default PATH for the vast majority of users, but I think backward compatibility makes this difficult.
Regarding item 5: I agree wholeheartedly. I have actually taken to reporting Git issues in the Debian BTS, for exactly this reason: so they don’t get lost.
On 4:
@pclouds: Wow, i’ve never noticed that before. this is spot-on perfect. Distros! Heads up!
@josh: I guess the backwards compatibility concern is the reason this isn’t enabled by default. Shame!
@gregf: looks like this build option gives you what you want, command completion for commands humans can use.
On 2:
@pcclouds: thanks for the heads up!
http://news.gmane.org/find-root.php?message_id=%3c7vpsb36yem.fsf%40assigned%2dby%2ddhcp.cox.net%3e
This idea was put down heaviliy it seems, showing a *deep* lack of understanding of learning curve. What can we do?
Check out this *lovely* quote… “So i think having the default geared towards advanced users and not newbie users is O.K.”. Thanks guys…. This thread makes me feel really sorry (and thankful!) for Carl.
@josh: yep, in some sense it was better with git-update-index as concepts weren’t collapsed. I n terms of history, i prefer it back in really early git when it was called a cache
regarding 3.1, what is the sense in having a local pull be any different to a merge?
good to see there’s agreement on 1, 3.2 and 5 though!
The one thing that I think that causes the most problems for users with git is the fact that the index is a first class concept instead of being a hidden power feature. Worse, the thing is NOT explained to users in tutorials, leaving users to assume that git acts like other VCSes when it doesn’t. I wrote up
http://www.gnome.org/~newren/temp/blog-entries/limbo.html
(which I’ll be posting to my blog in a couple weeks.) I had Thomas Thurman read over my various posts (others are reachable from http://www.gnome.org/~newren/temp/blog-entries/topics.html, though some are now obsoleted by actual blog posts), and his comment on that page about git was, “Oh, that’s why I could never figure git out. I understand it now.” I don’t think renaming is enough. It *NEEDS* to be explained if it remains a first class concept.
Oh, and yes, I’ve read the git archives about this subject. I disagree with Carl’s suggestion there. He wanted to only change the default behavior of commit, which would make git have no consistent model. I’d prefer that either (a) the index be explained up front to new users instead of being ignored (this includes explicitly listing gotchas associated with it), or (b) the index be made a second class citizen (i.e. available only with extra options) for _all_ commands. Whatever happens, the choice needs to be consistent and it needs to be explained up front. (I also think other VCSes need to explain the “you need to explicitly ‘vcs add ‘ gotcha upfront and do a disservice to users by ignoring this gotcha until later.)
“4. Bug your distro maintainer. Setting gitexecdir in config.mak should work”
That is wrong. Either git should have this behaviour, or not.
It is BAD to make this a job of distros. We all know how split up the communities will become if you leave something in the hand of distro maintainers!
These are definitely some notable problems. Fortunately, some of them are already in the works to be fixed.
“In general git has some terrible cryptic error messages.”
Send patches! Keep the error messages short, though. I’m finding the longer error messages grate after a while. And it’s harder to remember the errors and google for them when they’re long. Cryptic is bad, but terse is good….
“The one thing that I think that causes the most problems for users with git is the fact that the index is a first class concept instead of being a hidden power feature. Worse, the thing is NOT explained to users in tutorials”
Not true: see http://www.kernel.org/pub/software/scm/git/docs/tutorial.html. Or http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#how-to-make-a-commit.
I don’t know about tutorials elsewhere, but by now anything in the in-tree git documentation should have a pretty clear explanation of the index right up front. If you find any exceptions, please point them out and we’ll fix them.
1. Agreed.
2. It is called the staging area in the user manual. It’s called the index for a good reason – it’s an index of the working copy’s files.
3. Branches have Namespaces per remote. This is a good thing.
4. Git has a command-line API. That’s part of why it’s so cool. Point them at “git help”
5. There is the TODO file in the distribution, you can always submit a patch to that to lodge a longstanding issue that isn’t fixed. what more to you want? someone else to make the code do what you want?
@she:
damn right!
@bruce: I’ll certainly be submitting some patches for error messages, at least there’s clear agreement that there’s an issue there.
@sam:
2) The main problem is the collapse of concepts introduced by 1.5 wrt to git add and git remove, and those changes were basically introduced because the concept of the index was unclear.
3) why would that make pull and merge have different behaviour?
4) Thats still not a good argument against having the low-level operations in libexec, with a suitable pkgconfig variable for the location. Hell you can even mitigate backwards compatibility issues by having git-sh-setup add that to the path.
5) find -name ‘TODO’
robtaylor@lancastria:~/projects/git/git$
I think there’s consensus that a bug tracker is needed, so thats something to take to the ml and help set up.