Most of people's problems with git is that they don't realize when they're digging into git's internals and suddenly start asking "why is this different?" Usually this happens because they read something on stack-overflow and decided to copy and paste shit without actually thinking about what is happening.
I made a rather lengthy post on here some time ago that I need to find that specifically rebutted the git koan's examples. A lot of them purposefully choose the most roundabout ways to illustrate a false point. Most of people's complaints about git are formed out of ignorance and sometimes willful ignorance; that site only serves to perpetuate it.
Git's man pages are only terrible if you're technically illiterate. The example given perfectly illustrates this. The man page is concise and clear, the information is all there.
Perhaps the ignorance and the technical illiteracy go hand in hand? In case the man pages are somehow not clear there is a very good resource devoted to explaining fundamental dvcs/git concepts to beginners:
Most of people's problems with git is that they don't realize when they're digging into git's internals and suddenly start asking "why is this different?"
Several of the Git Koans points, most notably inconsistent and odd flags, should have nothing to do with how internal you are. There's no reason I'm aware of that the flags couldn't have been made more consistent.
Git's man pages are only terrible if you're technically illiterate.
Ah, the "everyone who disagrees with me is a bumbling idiot" approach.
Do you really think that the suggested man page in that post isn't any clearer or easier to read?
should have nothing to do with how internal you are
How do you figure that? They're completely seperate commands. Most of the time people are just dealing with wrappers/aliases around more "to-the-metal" commands. Why would the flags not be different?
Ah, the "everyone who disagrees with me is a bumbling idiot" approach.
That's not what I said but thanks for trying to be dismissive; you're only hurting yourself. Point out to me specifically what part of the man a developer would not understand. The author's revised man page is far less concise than the man page; it's just less technical and somehow the author thought that was "better." It actually ends up hiding information about what git is doing. Please tell me how that helps anyone.
As I stated in my post, if you are not familar with git or its concepts: git-scm.com is a great resource and you should utilize it. But don't pass off willful ignorance as problems with git.
Notice the spirit of your post: you only complain without any solutions; I offered a dedicated resource that explains everything in detail when you don't know what you are doing. But I guess that's the spirit of reddit in general.
Point out to me specifically what part of the man a developer would not understand.
From the link:
If one of -a, -s, or -u is passed, the command creates a tag object, and requires a tag message. Unless -m or -F is given, an editor is started for the user to type in the tag message.
What is a tag object? What are -a, -s, -u? Why is the -m/-F effect specified in Yoda speak?
Assuming I'm reading the man page to try to understand this, the document is useless. It may be somewhat useful if you already understand the majority of the command you're learning about.
You could rewrite that particular section as:
A tag with a message may be created using -a, -s, or -u. You will be prompted to enter a message, or a message may be entered with -m "message" or -F "message".
Now, I'm not sure what -F does, and the man page from the link doesn't help explain it at all. If -m and -F are equivalent, why do they both exist? If they aren't, why isn't that clarified?
I seems that man page avoids explaining anything to someone who doesn't already know what it means, and starts from the most specific need gradually reaching the most generic. However, unless you already understand the commands involved you need to keep track of every specific instruction to even know what the generic result would be!
You're trying to suggest that Git is ineffective. I don't think that's the case. The millions of dollars of software I've shipped using it also don't think that's the case.
Git is not the most UI friendly tool but it's not hard to learn and use on a daily basis to work all stages of a product lifecycle.
No, we think it could be much easier to use than it is. There's essential complexity that comes from "We are solving a complex problem so we have a complex solution." Then there is accidental complexity, where things don't need to be this complicated.
It's not obvious that you need to add -a to branch to see all branches [upstream] but that's not "hard" ... it's in the man page for git-branch ... etc. But that sort of inconsistency (while a flaw in the UI) hardly makes it complicated.
Yeah, you do, and I use Git for everything I do. That doesn't mean it can't be improved so that newcomers don't have to suffer the same pains we have. It doesn't have to be this hard. You could have a cleaner, more consistent interface without sacrificing one ounce of Git's awesomeness.
I agree completely. I'm not advocating for some third-party shim. This should really be addressed by the Git developers, and I'm pretty disappointed that it still hasn't, especially when they just rolled out a new major version and broke backwards compatibility anyways.
You don't give any actual examples for the last three out of 4 things.
Git's man pages are terrible.
What does this even mean? Without examples its just some guys opinion, and even more without examples it makes you look like you don't understand git.
If I don't like something and I don't have any concrete examples of WHY it is actually bad, I always say "I don't like x. I don't have any real reason for it, but I do". That way my ignorance doesn't end up making other people think something is bad when most likely it isn't.
The author basically admits the jargon is unfamiliar to him (which as a developer none of that should be) and he couldn't be arsed to actually read anything further when he came across something that wasn't spoonfed to him.
There's an entire resource devoted to helping people understand Git, under nearly every Git community I am part of constantly references it, but of course admitting that this information has already been compiled and extensively used would make the author look like a bozo so let's just all ignore it.
You don't give any actual examples for the last three out of 4 things.
Read the Git Koans post. It gives examples for all of this. My comment was a summary, hence the "To summarize...".
What does this even mean? Without examples its just some guys opinion
Again, the link I provided shows a concrete example of how it can be improved. Git's man pages seem to make a lot of assumptions about your base knowledge of how git works. It could do a much better job to explain itself to newcomers (again, see the example).
57
u/slavik262 Jun 19 '14
Git's UI is terribly inconsistent and wonky. See git koans.
To summarize, if you don't have the five minutes to read something hilarious:
Git ignores attempts to alias core commands, but doesn't warn you that it is ignoring them.
git checkoutdoes several completely unrelated things in different contexts.Flags for various git commands are terribly inconsistent.
Git's man pages are terrible.