The treatment of deltas is still not quite right.

[Cogito]

Previously this text misrepresented how git stores objects, first implying that it worked with deltas and then that it used deltas as the primary way of storing commit information.

In truth, deltas are only used when compressing the object store, and this is a relatively rare event.

This commit attempts to be both clear and precise with the basics of git storage, without going into too much detail. It aims to be a firm and correct base from which advanced understanding can be derived.

[pcottle]

Thanks for the draft @Cogito. This is a nice start, but I'm a little worried about

Every file included in the commit is copied from the directory to the repository's *object store*, and an *index* of each file's location is stored with the commit.

A newbie is probably thinking what's an object store? What's an index? Is the index something like C1 that I checkout? I normally just use Dropbox for my version control -- why is this so complicated?

Similarly for this line:

git reads the objects referenced in the commit's index from the object store and writes them into place in the directory

In one sentence we have object, commit, index, and object store. That's a lot for a complete git n00b to parse. If you contrast this with the majority of git beginner tutorials, the majority of them just say it's a "snapshot" and move on. It's really fine line to walk. I don't want people to get overwhelmed on the first tutorial :P Actually to be honest it's already a bit verbose...

I like your other edits though (a commit in a git repository) and your last line. I'll pull these in...

[Cogito]

Yes I agree it is hard not to overwhelm newbies. Interesting question from that - who is the audience of this project? I tried to write for someone who has used git but does not know much beyond the very basics.

I was trying in some ways to define those terms, but I agree this might not be the correct place.

I definitely think that this is not the right place to introduce deltas, particularly as they are relatively insignificant for how the majority of git works. They are a little visible (in the 'resolving deltas' sense) but they get a treatment here which is probably unnecessary.

I might have another crack at it, particularly if you can outline the audience we are targeting here. Might even be worthwhile adding that to the Readme?

[pcottle]

I'd like people to start thinking graphically as soon as they start working with git, so ideally it's a complete beginning (or someone just after that) using the service. Someone should be able to have 0 git knowledge, use the first 5 screens of try.github.com, and then use LGB. That low of a level... so yeah, it might not be the right place, but this distinction should be laid out somewhere because I certainly found it interesting.

I'll add that to the Readme, and your name! That reminds me, I should throw in everyone else who has contributed...

[Cogito]

That is what I figured you must be aiming at, after your last comment, and
I think it is the perfect audience for these initial lessons.

I am concerned about the deltas, insomuch that we might lead a newbie down
the wrong mindset from the start. A lot of other SCMs use deltas as the
basic storage option, and git is different precisely because it doesn't
(among a few other things). The fact that changing branches is so quick and
easy is a really big thing that people coming from, for example, SVN would
never even to begin consider possible.

Regards,

Andrew Ardill

On 17 February 2013 18:06, Peter Cottle notifications@github.com wrote:

I'd like people to start thinking graphically as soon as they start
working with git, so ideally it's a complete beginning (or someone just
after that) using the service. Someone should be able to have 0 git
knowledge, use the first 5 screens of try.github.com, and then use LGB.
That low of a level... so yeah, it might not be the right place, but this
distinction should be laid out somewhere because I certainly found it
interesting.

I'll add that to the Readme, and your name! That reminds me, I should
throw in everyone else who has contributed...

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/13#issuecomment-13681874.