Re: git annoyances

[Jeff King <peff@peff.net>]

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