On Mon, 11 Jul 2005, Eric W. Biederman wrote:
>
> I'm having the worst time putting together a mental model of how git
> works, and the documentation is spotty enough that it hasn't been
> helpful. So I am wading through the code. It seems every time I turn
> a corner there is another rough spot.
Btw, I know I'm bad at writing docs, but what I _do_ enjoy doing is
answering reasonably specific technical questions, and maybe somebody else
can write docs by taking advantage of me that way.
I tried to write the tutorial in a way that it also tries to explain how
git works (not just a "do this", but a "you update the index file and then
write the result out as a tree object"), but it obviously covers a fairly
limited part of what git actually can do, and at the same time it doesn't
go into a lot of detail.
And part of that is not just my inability to write documentation, it's
also that I just have the wrong "view" of the project, ie I probably just
take a lot of things for granted and consider them obvious, even though
they aren't, and then I probably occasionally explain things that aren't
worth explaining, because either they _are_ obvious, or people just don't
care and they are irrelevant.
I'd love to see somebody write up more of a "this is how you use git" kind
of tutorial, _and_ on the other hand more of a low-level explanation of
the notion of an object store where objects refer to each other by their
SHA1 names, and how that is represented in the filesystem and/or in packs.
Something with a few pictures would be great (ie screenshots of gitk, but
also something that tries to just visually show hot tags point to commits
that point to parents and trees, and trees pointing to other trees and
then blobs).
All things that I'm a complete idiot at, but that would help users
visualize what the heck git is actually _doing_, so that they don't just
parrot some magic command line that they don't understand, but can
actually reason about what they are doing.
I think a lot of people do understand this, but yes, the docs are kind of
lacking.
Linus
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
