Re: multi-project repos (was Re: Cleaning up git user-interface

[linux@horizon.com]

>> A lot of the complaints seem to not be about the interfaces, but about 
>> people not _understanding_ and knowing what the interfaces do. If you were 

> From the point of view of a user, there is not really a difference
> between the two.  As a user, you form a mental model of how things
> work by looking at the interface.  If the interface is bad, the user
> creates a faulty model in his head, and starts doing things that
> are perfectly logical in the faulty model, but stupid and silly when
> you consider the actual internals.

"The only intuitive user interface is the nipple; all else is learned."

As Linus is explaining, the fundamental *problem* is the mental model.
Once you know how to break your goals apart into the right kind of pieces,
little things like terminology are truly little.

I'm not sure that git is sufficiently like anything else that a few
well-chosen command names can bring a good analogy to mind.  There just
isn't a simple analogy that won't lead you astray; you have to understand
the thing on its own terms.

How do you explain the point of an electric screwdriver to someone who's
never seen a screw?  He'll think it's a silly way to wind up yarn.


I'll be the first to explain that the git docs have some major problems.
"git show" is a really useful command.  It has a zillion options to do
cool things.  Have you read the man page?

Didn't take long, did it?  "git log" is even more powerful, and almost
as bad.  The information is all available, it's just on the plumbing
man pages.

And I even understand *why* it's there.  Because writing the plumbing is
when the coders were thinking about the problem.  And writing good docs
is very simple: when you learn something, write it down.  Not later,
or next week, but right now, when you still remember how confused you
were before and what led you to the revelation.

The only problem, for a person looking at it top-down, is that git was
written bottom-up, so the bottom is very well documented, and once you
understand that, the top is pretty obvious and trivial.

But if you want to improve the situation for someone like yourself,
the solution is the same: when you learn something non-trivial, write
it down.  Not later, after you've finished learning, but right now when
you still remember the process of learning.

Now, when you show people what you wrote, one of two things will
happen:
1) They'll say "thank you, that's a good way of looking at it", or
2) They'll say, "that's not quite right; the truth is actually...".
   The second case means that you have a bit more to learn.
   But by taking the first step, you've given the learning process
   some momentum.  It gets easier after that.

I hope my recent postings ([DRAFT] Branching and merging with git)
form a reasonable example of that.


There are a few key concepts in the git tools.  I don't care if
"git-rev-list" is an ugly name; the name isn't learly as important as
realizing that *every* command that works on a list of commits uses
the same primitive, and what you learn about one command in that family