Re: git annoyances

Ingo Molnar [off-list ref] 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.

Junio C Hamano wrote:

The introductory documents may need to be updated to teach explicit "git
pull $repo $branch" form first,

Hey Junio,

I'm hearing you here! :-)

I think a furtherance of this notion is to
teach "git fetch ; git merge" before "git pull".

Thanks,
jdl

On Wed, Apr 09, 2008 at 02:04:33PM -0700, Junio C Hamano wrote:

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.

For me personally, I think this bottom-up approach makes the most sense
to learning (this may look familiar from the commit message to a patch I
sent earlier):

  1. here is what "git pull $repo $branch" means
  2. here is a way to shorten it to "git pull $repo" (set up remote
     $repo)
  3. here is a way to shorten it to "git pull" (default to origin)

But I think there are people who will get to the list and say "why
didn't you just tell me 'git pull' in the first place?" That is, the
complaints we have seen in the past reveal _too many_ low level details
too quickly.

Maybe we have stepped too far towards "top down workflow
descriptions" and need to go back. I dunno.

Another way of thinking about it is that we need two sets of
documentation with the same information (heresy, I know!): one bottom-up
and one top-down. I think the manpages tend to be "bottom up"
references. Bruce's user manual is more "top down" describing workflows.
I wonder which one(s) Ingo read, and which helped the most.

-Peff

On Wed, 9 Apr 2008, Jon Loeliger wrote:

Junio C Hamano wrote:

quoted

quoted

The introductory documents may need to be updated to teach explicit "git
pull $repo $branch" form first,

Hey Junio,

I'm hearing you here! :-)

I think a furtherance of this notion is to
teach "git fetch ; git merge" before "git pull".

Amen!


Nicolas

 > 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.

Something along the lines of:

Error description
Why it happened
How to solve/Sugestion

-- 
[]s,
André Goddard

Junio C Hamano a écrit :

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.

A possible way it to, by default, make git print the full form of the 
command when a short form is used. So the user see the concept without 
having to read the documentation and learn it gradually. I personally 
like tools that act this way. It permit to make a basic and easy 
tutorial with short commands that let know the general concept and show 
the full potential of the tool.

A "short form" flag in a user (not repository) configuration file should 
allow to suppress the long form printout for the comfort of the users 
that don't want it.

--
Jean-Christian de Rivaz

On Thu, Apr 10, 2008 at 8:08 AM, Jean-Christian de Rivaz [off-list ref] wrote:

 A possible way it to, by default, make git print the full form of the
command when a short form is used. So the user see the concept without
having to read the documentation and learn it gradually. I personally like
tools that act this way. It permit to make a basic and easy tutorial with
short commands that let know the general concept and show the full potential
of the tool.

I think this would be a very nice solution, not only do you allow the
user to realize what it is they are doing, you also provide them with
an easy way to be more verbose. Perhaps they wish to switch from the
default short behavior to a somewhat different form (e.g., change a
default 'master' argument to another branch). When writing out the
full form each time the user gets an intuitive and gradual
introduction into the rest of git, without limiting them or more
advanced users.

 A "short form" flag in a user (not repository) configuration file should
allow to suppress the long form printout for the comfort of the users that
don't want it.

Or perhaps, as I mentioned in the thread on "friendly refspecs", a
"newbie" config option or command that turns on the informative
verboseness options. As such, perhaps a "long form" flag would be more
desired instead, to prevent existing developers from being spammed
with information they do not are interested in.

Cheers,

Sverre Rabbelier

On Wed, Apr 9, 2008 at 6:56 PM, André Goddard Rosa
[off-list ref] wrote:

quoted

 > 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.

 Something along the lines of:

 Error description
 Why it happened
 How to solve/Sugestion

Hi,

This actually touches on one of my main purposes  behind Pyrite.  I intend to
do the following things to help the situation and I was wondering what the
git community's reaction is.

1) Since it will be designed for end users I intend to remove the options not
designed for end users.  This will also shorten up the help so that the entire
help can be shown to the user when they encounter an error.

2) No unnamed options.  I think this would have helped the above case
although it would have required a *bit* more typing.  The command would
have looked like "pyt pull/fetch -r x86 -b latest"  Combined with the above
the command would have spit out the help and a message stating what was
missing.

3) No syntax.  Git has a lot of syntax.  It has refspecs, revision ranges,
symbolic names (although i do like these) that a user has to learn.  I
think this
is one of the most error prone parts of the git for new users.
Hopefully, I will
be able to find simple and straightforward ways for the user to supply
this info.

Any comments/suggestions will be appreciated.

Thanks,
Govind.