Re: I want to release a "git-1.0"

From: David Greaves <david@dgreaves.com>
Date: May 30, 2005, 22:11 UTC
Message-ID: <429B8FA0.1080903@dgreaves.com>
In-Reply-To: <Pine.LNX.4.58.0505301253070.1876@ppc970.osdl.org>

Linus Torvalds wrote:

Show 21 quoted lines

>So before I do a 1.0 release, I want to write some stupid git tutorial for
>a complete beginner that has only used CVS before, with a real example of
>how to use raw git, and along those lines I actually want the thing to
>show how to do something useful.
>
>So before I do that, is there something people think is just too hard for
>somebody coming from the CVS world to understand? I already realized that
>the "git-write-tree" + "git-commit-tree" interfaces were just _too_ hard
>to put into a sane tutorial.
>
>I was showing off raw git to Steve Chamberlain yesterday, and showing it
>to him made some things pretty obvious - one of them being that
>"git-init-db" really needed to set up the initial refs etc). So I wrote
>this silly "git-commit-script" to make it at least half-way palatable, but
>what else do people feel is "too hard"?
>
>I think I'll move the "cvs2git" script thing to git proper before the 1.0 
>release (again, in order to have the tutorial able to show what to do if 
>you already have an existing CVS tree), what else?
>  
>

It seems to me that a tutorial for end users is inappropriate. You should be writing a tutorial for porcelain implementors :)

Anyway, a while back I split the commands into manipulation and interrogation and then into ancillary commands and scripts. Do you actually agree with this grouping? http://www.kernel.org/pub/software/scm/git/docs/git.html It may help to position who should be doing what.

Also, if you're writing a git-init-script, it may be that you're simply scripting common processes and could helpfully maintain consistency by either pulling some of the really trivial Cogito scripts (cg-init, cg-add, cg-rm) into the core 'ancillary' area or suggesting modifications to Cogito as the current 'best of breed' implementation of the low-level git usage process. Cogito also 'fixes' some useability issues such as using "git-update-cache --add" == "cg-add" I know you _can_ use git as an end user - but it seems that it's designed to be used by plumbers.

Oh, I'd also like to see something along the lines of my cg-Xignore before git hits 1.0

On the tutorial side - yesterday I started pulling together stuff from the list about merging to complete the README where it says [ fixme: talk about resolving merges here ]

I haven't done much other than collect some discussion from the list and the text from git-read-tree.txt. I do think this area needs more explanation as the whole 'stage' thing is pretty alien to CVS. I also noted a few people asking "so I did this merge - what do I do now?"

The working directory/cache/repository is also confusing sometimes - especially when the cache and working-dir unexpectedly don't match.

I also see in my notes: "improve the docs around update-cache."

David