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

[David Greaves <david@dgreaves.com>]

Linus Torvalds wrote:

>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