Ingo Molnar <mingo@xxxxxxx> writes: > i just had a rather annoying session with git - here's the dump and > commentary, in case anyone is interested in usability fineprint. Thanks. It is always enlightening to see this kind of walkthru session to learn where the UI warts are. The ones with concrete suggestions for improvements are even more appreciated. > usually i just have a single git repo that tracks everything > interesting, but this time i did something i rarely do: i tried to merge > one local tree of mine into another local tree of mine. So i had no > commands (or even concepts) cached in my short-term memory that would > achieve this goal, i just tried the commands that i thought to be > 'obvious', without applying much (or any) IQ to those commands: > > $ cd linux-2.6-sched-devel.git > > $ git-remote add ~/linux-2.6-x86.git You told git that "I'll interact with this other repository from now on, so please help me with some extra settings to do so. Namely I do not want to keep typing it in full URL all the time so I want an abbreviated way to tell you I am talking about this remote repository, and also I want to have set of remote tracking branches for this one". Maybe "remote add" is not quite the right name to convey the above concept. > $ git-remote show x86 > * remote x86 > URL: /home/mingo/linux-2.6-x86.git > New remote branches (next fetch will store in remotes/x86) > base for-akpm for-linus latest master testing So the command did as you told it to. > $ git-merge x86/latest > x86/latest - not something we can merge You told git "I want to merge a commit into the current branch, and that commit is called x86/latest". Alas, no such commit exists in your repository (yet). Should we be saying "no such commit exists, you need to fetch it from elsewhere first"? > $ git-fetch x86/latest > fatal: 'x86/latest': unable to chdir or not a git archive > fatal: The remote end hung up unexpectedly "Not a git archive" should be clear enough. You already said "remote show x86" correctly above, and it makes me wonder why you are now saying "x86/latest", not "x86" without "latest". In other words, "git fetch x86". With that, you would tell git "Hey, I've already told you what I want you to do with this short-hand name "x86". It is the name for the long URL I've previously given you and I want you to fetch from that repository, and I want its branches to be stored in remote tracking branches in my repository". But you didn't. You are not taking advantage of your previous "git remote add". I am suspecting that a cause of this confusion is partly because earlier in 1.3.0 days we tried to make things easy for CVS migrants where they always interact with a single "upstream" repository and with _the_ single branch, and we were _too_ successful in doing so. That made us allowing the users to type "git pull" and "git fetch" without parameters. This is generally a good thing: shorter to type for doing common things is always good, as long as the user knows what he is doing. But at the same time, this allowed docs and cheat-sheets that mention only the form without parameters and not the normative "repository refspec" form. This dumbed down the users not understand that in that context fetch (and pull, which is a fetch followed by a merge) is always happening against a single branch of single remote repository, the way to name remote repository and its branch(es) is to give them as separate parameters, and their not typing the pair explicitly is a mere convenience feature. This particular aspect of the shorthand is actually very bad. It makes the mental model fuzzy, and hiding important rules of how the world works from new people would lead them to unnecessary confusion. In short, we made it harder for the new people to "get" it. The introductory documents may need to be updated to teach explicit "git pull $repo $branch" form first, and if they are short documents, end in introductory phase and leave the remainder to "further reading", they should probably be fixed not talk about the shorthand form "git pull $nick" and "git pull" without parameters at all. That may help fixing this mental-model breakdown. > $ git-pull x86 latest > > (that fetch+merge went problem-free.) Yes. Because git is distributed, a branch in the global scope is named with a pair "remote" and "branch" as two separate parameters, and we consistently do so. Always. Just like you are supposed to say in your "Linus, please pull" requests (e.g. http://article.gmane.org/gmane.linux.kernel/321590). > but it was a PITA and all of git's messages about the problem were not > only unhelpful, they confused me into looking for problems where there > were none IMO. Yes, we need to teach "git" to do more mind-reading (I am not being sarcastic). There should be a pattern in common user errors that share their roots to the same user misperception, and if we can identify that, maybe we can make git guess what the user was really trying to do and give better error messages than it currently does. > also, the first natural thing i did was to just type: > > $ git-merge ~/linux-2.6-x86.git/ > > which i naively assumed would sort things out for me and provide some > reasonable default behavior - but instead it just gave an annoyingly > unhelpful error message: > > /home/mingo/linux-2.6-x86.git/ - not something we can merge I'd agree that it is fair to get frustrated with this. We actually did not have "git merge" as the first level UI citizen for quite some time, and the way to merge in _anything_ was done with "git pull", even within the local repository. If you did not know "git merge" existed, the above would have been either one of $ git pull ~/linux-2.6-x86.git/ $ git pull ~/linux-2.6-x86.git/ master and would have been nicer. But people wanted "git merge" which is a purely local operation, which made (and still does makes) sense. But now people need to know two different commands, one that works globally and the other that works locally. C.f. http://thread.gmane.org/gmane.comp.version-control.git/10778/focus=10900 http://thread.gmane.org/gmane.comp.version-control.git/31351/focus=31528 http://thread.gmane.org/gmane.comp.version-control.git/31351/focus=31490 > there should really be a consciously established "route of failure > resolution" - directing people towards relevant sources of information > or commands when the git command-line utilities return some error due to > user incompetence. Otherwise users just guess around and get frustrated. Yes, I called it mind-reading above, but we are wishing for the same thing. by the way, because you already paid for your Shift keys, you might want to use it consistently to enhance readability. i find it somewhat irritating not to be able to tell where each sentence begins with enough visual cues (i.e. full-stop, two spaces and initial capital letter) and first person subject not spelled with capital letter i. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
