Re: Git in a Nutshell guide

From: Jakub Narebski <jnareb@gmail.com>
Date: Nov 20, 2007, 23:57 UTC
Message-ID: <fhvs95$5qk$1@ger.gmane.org>
In-Reply-To: <3057F6F3-BEAA-447A-AB79-A0AFB7DB8826@lrde.epita.fr>

Benoit Sigoure wrote:

Show 9 quoted lines

> On Nov 19, 2007, at 5:14 PM, Jonas Juselius wrote:
>> On Mon, 2007-11-19 at 17:05 +0100, Jakub Narebski wrote:
>>> Do I understand correctly that you don't support cloning via git://
>>> protocol?
>>
>> Yes, that is correct. The machine is behind a number of firewalls,  
>> and I simply cannot be bothered to go through the bureaucracy...
> 
> You can create a repository on repo.or.cz then :)

Which can then function as a mirror.

Show 5 quoted lines

> One of the things you said in your guide is that Git is easy to  
> learn.  I think this is wrong.  Git is way more complicated than most  
> other SCMs, especially compared to SVN.  Its documentation is far  
> behind, compared to what other SCMs have.  There is no real user  
> guide

What about "Git User's Manual"?

Show 5 quoted lines

> and the man pages are incomplete, at best.  I know saying this   
> is a bit harsh, especially to the people out there that are working  
> and sending patches to improve the documentation, but I think we have  
> to admit that it's true, even though Git is making progress on this  
> aspect.

That's sadly true, and confirmed (somewhat) by the fact that both in 2006 user's survey and in 2007 survey (see Git Wiki for summaries) one of more common requests are for "better documentation" and "The Git Book" (showing svnbook and hgbook as examples).

[cut]

I think that writing proper "Git Guide" aka "The Git Book" is hard because of some things:

 1. Git has many useful advanced features. Describing those advanced
    features is not easy. For example git uses multiple branches in single
    repository paradigm freely, which makes learning curve a bit steeper;
    IIRC hgbook describes one branch per repos situation (at least at
    beginning), which is easier.

 2. Git has some historical cruft, including the fact that it began as
    series of low level tools (plumbing) and became proper SCM (acquired
    proper porcelain) later, what can be even now seen in documentation...

 3. Explanation of some features (like object model) would be much easier
    with some graphics (diagrams etc.), but chosen documentation format,
    AsciiDoc, doesn't make it easy...

Yust my 2 eurocents.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git