[Agingcoder]

The git documentation is one of the nastiest docs ever just like the whole git ui. It’s technically entirely correct, but won’t help you understand how it works in any way.

It’s exactly like folks in 1995 telling you to rtfm when you’re trying to install Linux from a floppy disk. It’s doable, but annoying, and it’s not that easy.

[koiueo]

That's really unexpected. To me, git documentation was one of the best cleanest official docs I've ever read.

Just in case, I'm talking about the Pro Git book [0]. I remember reading it on my kindle while commuting to office by train. It was so easy to understand, I didn't even need a computer to try things. And it covers everything from bare basics, to advanced topics that get you covered (or at least give you a good head start) if you decide to develop your own jujutsu or kurutu or whutuvur.

[0] https://git-scm.com/book/en/v2

[Agingcoder]

This is exactly what I meant. https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-N...

The book says that ‘ To really understand the way Git does branching, we need to take a step back and examine how Git stores its data’ then it starts talking about trees and blobs.

At that point you’ve lost almost everyone. If you have a strong interest in vcs implementation then fine, otherwise it’s typically the kind of details you don’t want to hear about. Most people won’t read an entire book just to use a vcs, when what they actually want to hear is ‘this is a commit graph with pointers’.

I agree with you : the information is there. However I don’t think you can in good faith tell most people to rtfm this, and that was my point.

[rmwaite]

To be honest, if you’re using a tool that stores things as trees and blobs and almost every part of its functionality is influenced by that fact, then you just need to understand trees and blobs. This is like trying to teach someone how to interact with the file system and they are like “whoa whoa whoa, directories? Files? I don’t have time to understand this, I just want to organize my documents.” Actually I take that back, it isn’t /like/ that, it is /exactly/ that.

[Agingcoder]

I see your point but … trees and blobs are an implementation detail that I shouldn’t need to know. This is different from files and directories ( at least directories ) in your example. What I want to know is that I have a graph and am moving references around - I don’t need to know how it’s stored.

The git mental model is more complex than cvs, but strangely enough the docs almost invariably refer to the internal implementation details which shouldn’t be needed to work with it.

I remember when git appeared - the internet was full of guides called ‘git finally explained ‘ , and they all started by explaining the plumbing and the implementation. I think this has stuck, and does not make things easy to understand.

Please note I say all this having been using git for close to 20 years, being familiar with the git codebase, and understanding it very well.

I just think the documentation and ui work very hard towards making it difficult to understand .

[koiueo]

> I don’t think you can in good faith tell most people to rtfm this

I can, and I do.

The explanation in that book creates a strong coherent and simple mental model of git branching. I honestly can't think of a better explanation. Shorter? Maybe. But "graph with pointers" wouldn't explain it.

So let's agree to disagree.