[CuriousCosmic]

Okay serious question though. How many developers have actually read any of the git instructional material? Like beyond just peaking at the reference/man pages.

Git's docs have quite well written guides and introductory material but how many developers have ever even read those docs, even in part?

I can't think of a single other tool or library I use on a regular basis that has documentation but it's considered standard practice to just ignore all those docs and "wing it" based on colloquial knowledge and random copypasted snippets from stack overflow.

Everywhere else in the tech space RTFM is standard practice but as soon as you say that with git, it's interpreted as if it was said with complete and utter condescension.

(aside: you can still dislike git and there are perfectly valid reasons to but so often I see people argue that git is bad without ever having experience following the instructions printed on the tin)

[Ygg2]

If you need to resort to RTFM to use the tool, you've already lost. You don't yell at person for getting shocked and cut because the saw is just a motor with blade attached, and you need to start blade by shorting circuiting it with a graphite pen.

It means your interface (place where app and user interact) is hopelessly bad.

[slowmovintarget]

I don't think that's true, especially for complex command-line tools.

Reading the manual, especially when it's well written, can help you understand why design decisions were made with the tool. We're not talking about a simple tool without safeguards. We're talking about a complex tool with a lot of interacting pieces.

You do read the manual on that airliner as a pilot because it's your job to know the systems of the airliner. You do read the manual on the sonar system in the submarine, because it's your job as a sonar operator to know the system.

I dislike the shiny-plastic-button mindset that seems to infect everything these days. Professional tools tend to be more flexible and more complex than consumer tools, because professionals often need to do more, and get more out of those tools. Git is not Dropbox or WinZip. It has a far more complex function. If you have to read the manual to get full use from a tool, that's not losing, that's learning. It's part of the job.

And yes, I have read the Git manual.

[Ygg2]

> I don't think that's true, especially for complex command-line tools.

That's the issue. The interface a person sees, should be minimal when possible. Git can't claim it's not needlessly complex when tools like Mercurial and Sapling exist.

> You do read the manual on that airliner as a pilot because it's your job to know the systems of the airliner.

Man, if you are comparing Git to an airliner, you do realize people allowed to touch a real aeroplane consoles need months if not years of exams and hundreds of hours of practice in simulators? Are you saying Git should require the same? Because then the analogy doesn't work.

Any CLI that would require months of reading the manual and practising in Git sandbox would be deemed too complex for all but the most masochist of devs.

Git doesn't have to be that complex, but its fundamental file based "abstraction" combined with keeping it exposed to end users leads to problems.

As someone said, Git isn't a Version control system, but a Version control toolkit, that you shape into a system. And everyone has a subtly different way of thinking how it should work, so you end up with some very bizarre workflows.

> I dislike the shiny-plastic-button mindset that seems to infect everything these days. Professional tools tend to be more flexible and more complex than consumer tools, because professionals often need to do more, and get more out of those tools.

And I dislike the RTFM mentality that is pervasive in the OSS sphere, but here we are. I don't want to think about what exactly the Git is doing, and "Why is Submodule eating my directories?". I want to write code.

Look, it's fine to RTFM when it's you and your buddies are writing a kernel in 1980. Not when it gets used by millions of developers.

[MaxBarraclough]

> If you need to resort to RTFM to use the tool, you've already lost.

Git is a power tool aimed at professional-level software developers. If they tried to make it idiot-proof, it would probably stop being useful. It would at the very least bring considerable restrictions.

[CuriousCosmic]

It's not a matter of "you have to do x dangerous thing to make it work".

That's the issue. To repeat the meme, if you are "doing git properly", you absolutely should not be doing anything dangerous at all. There are a few tools that do unintuitive things for historical reasons that you are recommended to use their replacements instead (prime example: using checkout to change or create branches) but the overwhelming majority of tools in the git suite don't have that issue. And for the tools that do have that issue (like checkout), you'll see that the docs consistently recommend users to use their replacements instead when performing operations.

But what you have is a ton of people who don't know how to safely work in a shop insisting you need to use tools improperly and often for the wrong purpose entirely. Things like "use a push block or push stick (even if it's just made from scrap) when feeding material through a table saw to keep yourself from getting injured", "don't try to use a miter gauge with a rip fence", or "for the love of god don't freehand pieces through the saw".

Just because you can use a tool wrong doesn't mean it's acceptable. There's a lot of standard practice in shops that you'd learn by reading the instructions but plenty of people just wing it either out of laziness or out of ignorance and then get hurt.

That doesn't make RTFM any less relevant, it only makes it more relevant.

[Ygg2]

> That's the issue. To repeat the meme, if you are "doing git properly"

That's not a meme - that's just a True Scotsman fallacy.

What about Submodules? Well, all true Scotsmen™ don't use submodules.

What about pushing upstreams in Subtree? Well, all true Scotsmen™ don't push upstreams in subtrees.

What about ours/theirs? Well, all true Scotsmen™ know how what that refers to.

What about X? Well, all true Scotsmen™ know (not) to use X.

---

This line of thinking glosses over the complaints of many people by constructing a magical Perfect Git User, that instinctively knows the outcome of every command in every situation over a timespan of eons, for any code base.

---

> Just because you can use a tool wrong doesn't mean it's acceptable.

A conscientious toolmaker would ensure that the number of ways a tool is misused it small and will craft affordances to stir people using them into pits of success, rather than just Hole-Hawging[1] the user when they make an error.

[1] "At some point, the drill bit caught in the wall. The Hole Hawg, following its one and only imperative, kept going. It spun the worker's body around like a rag doll, causing him to knock his own ladder down" source: https://web.stanford.edu/class/cs81n/command.txt

[CuriousCosmic]

It's not "don't use X" it's "don't use X without understanding its limitations and without knowing when you should vs shouldn't use it". There's a nuance here and that nuance is in the manual.

Again, it's not "don't do X", it's "don't do X until you've read the manual and you understand what X does and when you should use it versus another tool in your arsenal".

If you want to go through the list:

> What about Submodules? Well, all true Scotsmen™ don't use submodules.

Use submodules. They actually have some pretty justified use cases but for what a lot of people want them for (having a dependency that they don't intend on ever modifying other than updating which version it points to), you shouldn't use them and should use a build system's dep manager (or a script, a branch, and a worktree) for that.

Old submodules had some major warts and were deprecated with everyone quietly moving up to modern submodules. Modern submodules actually aren't that awful and haven't been for at least 5 years. If you need to contribute changes upstream from your embedded repo, you need the entire repo, and you don't intend on having history cross the submodule barrier at all (or extremely rarely at most), then you actually probably want to use submodules and you should use them.

The manual covers basically all of that

> What about pushing upstreams in Subtree? Well, all true Scotsmen™ don't push upstreams in subtrees.

Subtree isn't part of git. They are contributed software. More details as to what that means are linked below but the short of it is that they are included as a convenience and should not be treated as anything less than a third party tool, often an experimental one:

https://github.com/git/git/blob/master/contrib/README

As for subtree merges? Yeah those exist and the manual covers them. You want to push to a subtree upstream? Merge the subtree into a local copy of the upstream branch with the `-Xsubtree=rel/path/to/subtree` option. This will take your whole history with you so you'll need to either squash those changes or rebase them (both approaches are covered in the advanced merges chapter along with the subtree merges).

> What about ours/theirs? Well, all true Scotsmen™ know how what that refers to.

Thank god the manual covers that (chapter: advanced merges).

----

Again, RTFM.

[Ygg2]

> It's not "don't use X" it's "don't use X without understanding its limitations and without knowing when you should vs shouldn't use it". There's a nuance here and that nuance is in the manual.

That's what I was saying. "Don't use X" is same as "Don't use Z when Y and Q" if X is "Z when Y and Q ".

Also that's not how people work. People want to get shit done. They don't care about Git or X or RTFM or Wayland or whatever. Their mental model needs to be close to how Git behaves. Not the other way around.

> having a dependency that they don't intend on ever modifying other than updating which version it points to), you shouldn't use them and should use a build system's dep manager.

Great idea, except that's not how people use it in the wild. Manual is great in theory (like if you and ten of your buddies write code). Not in practice, where millions use it.

First, not all language have build managers nor do people even talented devs use it as instructed.

Know what would make it easier? Either having submodules working in all cases, or not having it at all.

> Thank god the manual covers that (chapter: advanced merges).

That's not the point. If you have 10sec and you are doing a cherry pick what is ours/theirs?

No manual available.

In practice people don't read manual to do X, they have preconceptions/ mental models how Git works and consult manual when things go pear shaped.

> Subtree is contributed software

I don't think you'll find two people doing non-Git programming that care about that factum.

[CuriousCosmic]

> That's what I was saying. "Don't use X" is same as "Don't use Z when Y and Q" if X is "Z when Y and Q ".

If you want to reduce knowing "proper use of tools" ad absurdum, then there's basically no reason to care about the difference between a linked list, an array, a vector, a hashmap, etc. They are all basically the same thing and if you use one that isn't designed for the problem you have, it's not you that is wrong, it's obviously the container is just bad and you shouldn't use it.

Tools have a purpose and different problems have solutions that better fit them. You might run into issues with a tool or solution to the problem if you don't understand its purpose/use and you try to use the wrong tool for the job.

> Also that's not how people work. People want to get shit done. They don't care about Git or X or RTFM or Wayland or whatever. Their mental model needs to be close to how Git behaves. Not the other way around.

Sure and do you know how you get that to happen? You have them RTFM or at minimum skim it so they can understand the tool and construct their mental model in alignment with the tool when they are learning how to use it the first time.

Like I'm not saying you need to sit down and read all 500 pages of the pro-git book in one setting. That's way too much and the user won't retain that. But like whenever you want to do something that you haven't done before, go to https://git-scm.com/, search it in the search bar, and see what comes up. Or just click Documentation, then Book, and pick the chapter for the thing that roughly approximates to what you want to do. A given chapter of the git book (presented as a single page via the HTML version) generally takes less than a minute or two to skim through to find an answer. Then the section that answers your question might take another 2-5 minutes at most to read and digest before you have your answer. Or if it's something relatively trivial, hit the man page/reference for the command. It's enough to solve the overwhelming majority of people's problems while also helping them gradually build/align their mental model with the tool.

> Great idea, except that's not how people use it in the wild. Manual is great in theory (like if you and ten of your buddies write code). Not in practice, where millions use it.

> First, not all language have build managers nor do people even talented devs use it as instructed.

Is it not common for projects to insist on submodules for dependencies they want to heavily modify instead of just forking the dependency into it's own repo, doing development for the forked dep there, and then just tracking the fork with the submodule? If not, why aren't they using a subtree merge instead?

> Know what would make it easier? Either having submodules working in all cases, or not having it at all.

You have three separate approaches that solve different sides of the same problem: build tool dep management, submodules, and subtrees. Instead of trying to solve the entire problem with one approach, why not just support separate solutions that are tailored to the needs people have? Each has tradeoffs and you shouldn't use one when you would use the other.

> That's not the point. If you have 10sec and you are doing a cherry pick what is ours/theirs?

> No manual available.

Ours is our branch (i.e. the branch you are currently on and merging into), Theirs is their branch (i.e. the branch you are trying to merge). The mental model is that you are merging in someone else's changes into your code, i.e. you merge theirs into ours where theirs and ours have a common ancestor.

> In practice people don't read manual to do X, they have preconceptions/ mental models how Git works and consult manual when things go pear shaped.

Exactly and that's fine. But if you don't know what you are doing (ex: if you haven't done it before or it's been a long time), instead of just bumbling ahead, try taking a minute to check the manual and verify that your assumptions are right.

It's like trying to go somewhere, if you go to that place regularly, you can probably navigate blind but if you haven't been there before or you don't know the area, you should probably look at the map first and then ask for directions if you can't figure out where you are or where to go next.

> I don't think you'll find two people doing non-Git programming that care about that factum.

Oh sure but the point is that complaints about subtree are not complaints about git. They are complaints about what is basically an unofficial hobby/side project of one of the developers and more importantly complaints about a piece of code that isn't necessarily guaranteed to be held to the same standard as code that is actually part of the git project.

[CRConrad]

> How many developers have actually read any of the git instructional material?

At least one.