Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Felipe Contreras <felipe.contreras@gmail.com>]

On Thu, Nov 12, 2009 at 1:29 PM, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> Feel free to bring this issue on for a change in Git 1.7.0. It would be
> good to research any possible incompatibilities this would imply (other
> than the looks of the output),

Isn't that what we are doing just now?

> The process can be frustrating at times. Many patches go through many
> rounds. I've had occasions where I got frustrated and gave up, as well
> as those where I learned a lot and the actual result was much better
> than it would have been without thorough discussions. It's this process
> which tries to ensure that the project is moving forward most of the
> time, rather than sporadically back and forth; moving forward maybe a
> bit slower, but still at an impressive overall rate.

Except in this case there is no path forward. If there is, I would
like to hear it.

> Regarding this specific patch series: I took part in the initial
> discussion, and got frustrated by the original poster's seemingly
> unwillingness to accept advice, so I left. I'm not drawing any general
> conclusions, and please don't take this as an ad hominem argument.
> Sometimes it's simply a matter of mismatching participants.

What are you talking about? All your comments were addressed in
subsequent patches, as the commit message of the patch in this thread
points out.

Moreover, in the paragraph before you argued that these thorough
discussions are actually a good thing. Or are patch committers not
allowed to discuss?

> I didn't read that out of the survey. On the other hand, the last survey
> pretty impressively showed where it had been publicized most
> prominently. One should keep that in mind when interpreting the results.

So? What are the surveys supposed to be for, if not to use the results?

> If you care to go back to that discussion you see that there is good
> reason for having both --cached and --index. They are different. "git
> help cli" explains this nicely.

"good" is a very subjective term; I don't think "they are different"
is a good reason. By that logic --only-index and
--index-and-working-dir serve the same purpose, just like --gogo and
--dance.

But there's no point in discussing this until people accept there is a
problem, and there seems to be unwillingness to accept that very few
people use the stage properly.

> "To stage" has been introduced to describe what "git add" does to people
> who hard wire "add" to the meaning it has in other VCSes. In fact, this
> would be unnecessary if the concept of Git as a *content* tracker could
> be transmitted more successfully. Git cares about content only, so what
> could "git add" possibly mean?

usage: git add [options] [--] <filepattern>...

I don't see any mention of this "blob" mythical creature. In the vast
majority of the minds of git users, 'git add' adds files to the
repository, just like any other VCS.

Proof of that is that only 23% of the people use "git add -i / -p" and
15% "git add -u / -A" often.

> "git stage" is a failed follow up ui experiment.

I agree with that. But assuming because one UI experiment failed, all
other "stage" proposals are doomed.

> In this regard, I think the problem is that there are really two kinds
> of people in terms of learning style:
>
> - Some prefer recipes, similarities with previously known recipes. "How
> do I...?" And then try do understand "How does (G)it...?" from that.
>
> - Some want to understand concepts first: "How does (G)it...?" And then
> figure out how to use (G)it to do what they want.
>
> I'd guess most developers and a large fraction of the "technical crowd"
> belong in the second camp.

I actually belong to the two groups. When I started to use git I
learned it through recipes and grew fond of it, but didn't really know
what was really happening even thought I used it for years. It wasn't
until a colleague recommended me to read "Git from the bottom up",
then I really started to understand git and realized I didn't know
squat. Sure, I heard concepts such as "feature branches", "rebase" and
"stage interactive", and I had in my to-do list to learn them, but
that was it.

I'm pretty sure the vast majority of users are in the darkness just as I was.

> I still think we should both

What?

> - try and teach concepts early, emphasize that Git is different
> (content, index, branch - that's it)

Well, that's the first failure right there. If your objective is to
confuse people, then sure, call it "index", otherwise choose a name
that corresponds with it's purpose: stage.

> - make Git behave in "expected ways", making it easy for the (willing)
> beginner) without compromising its usefulness as a power tool.

Sure, but if the UI was more friendly people would learn to use the
advanced features through it's use. Currently there are no ropes to do
that. You have to read a book or something.

-- 
Felipe Contreras