Damn yo, that's quite the domain name you snagged for this project! My only criticism would be the "typing", it feels unnecessary, when you just want to navigate quickly around.
I'm on the fence about the "typing". It does come across as gimmicky, but it also is a good way to show exactly when the contents of a sizable text field changes.
The "typing" of the results are horrible. It just adds a few seconds where you just sit and wait for the answer to be finished for no apparent reason. Doesn't help that the default is the slow typing speed. I could never recommend this to a colleague to explain or help with git because of how frustrating I find the "typing".
It's nicely done but unfortunately it would still be faster to type something in a search engine and check the result.
I think it could improved by adding a free search text box, and maybe by not having a second dropdown list. Instead of making the user select something (sometimes you might no even be sure what to select), display all the options directly - since it's just one line of text anyway it won't take much space.
I'll never get why people complain about git being confusing when "man gittutorial" and "man giteveryday" are top-notch entrypoints into the git documentation.
I've been using git for years and I've never heard of these. Thanks for shouting them out.
This is something I've been thinking about lately. I feel like every tutorial needs a list of documentation right at the top before it gets into whatever specific path through the "forest of knowledge" of the topic at hand.
Lots of exclusively technical types don't understand why people are confused by heavily documented but awful interfaces. That's why HFE became a field and why UX practices should inform software development from the get-go.
Documenting a lousy interface is not a solution— it's a mitigation strategy and usually a lazy one. Most people find git's interface to be confusing, arbitrary, and frequently astonishing in destructive ways. Maybe you're exceptionally gifted in keeping a large bank of seemingly arbitrary commands in your head, or maybe you speak git frequently enough to have native proficiency. Unfortunately, you can't generalize that to all other users, and it doesn't invalidate their difficulty.
Since most folks new to git are likely new to CLIs— having a tutorial two levels deep in man pages makes it nearly useless. If you draw two barely touching circles on a page and label one "people confused by git enough to need a tutorial," and the other "people who know what man pages are, how to access and read them, and think to look there for tutorials,"— that's your usability Venn diagram for that documentation. Beyond that, many organizations require non-developers to use git now— copywriters, designers, project managers, etc. We're not talking about sendmail or clang here.
That lack of developer empathy for less technical end-users is why software projects, especially FOSS ones, marginalize UX input. Usability is the one thing commercially-sold software consistently does better than FOSS, and one of the reasons commercial offerings so frequently trounce FOSS equivalents in everything but developer and system/network tools used by people with bad UI Stockholm Syndrome. When monetary incentives and non-developer input inform product decisions, "it's in the docs" just doesn't cut it.
I've primarily worked in tech for the past 25 years, been a full-time developer for 10 (exclusively writing FOSS,) and have recently moved towards design because I see a lot of unmet needs there. So I understand the frustration in user needs precluding the most elegant/interesting/efficient technical solution to a problem. But, if you aren't actively working to meet end-user needs, frustration about end-user confusion isn't particularly justified.
As an aside, I believe Firefox's comparative success among end-user-visible FOSS projects stems from the Mozilla Foundation's commitment to product usability. Check out https://firefoxur.github.io
Oh, sorry— I read too quickly. I was specifically thinking of Human Factors Engineering, though I'm sure Human factors and ergonomics is quite related.
As a quick answer because it popped into my head, The Design of Everyday Things by Don Norman is an obvious first stop on that trip.
Introductory courses on LinkedIn Learning (formerly Lynda.com) are an excellent place to get a foothold for how it's done today. I believe many public libraries will give you remote access to LinkedIn Learning!
I think "Don't Make Me Think" is a bit overrated, but many people find it very useful.
Personally, I started a BFA in graphic design, then switched to interaction design which has a heavy UX/User Research… the programs are very similar at their cores because the thought process is very similar among different design disciplines. That’s probably not feasible for most, however, and I should have a better answer for this excellent question.
> Lots of exclusively technical types don't understand why people are confused...
It's not that they don't understand, it's that non-technical people often proactively avoid carefully reading the few lines of relevant documentation. That's something a technical person can tell from the second the non-technical tries to ask a question.
> When monetary incentives and non-developer input inform product decisions, "it's in the docs" just doesn't cut it.
Obviously, you have the right to ask any question if you're paying for someone's time: you become a "client". Otherwise, yes please read the docs.
To be fair, I’m fairly technical and I also proactively avoid reading the documentation. In the ideal scenario the interface to whatever I’m using is self explanatory, and I don’t run into any issues.
It’s only if the product has a less simple interface that I have to fall back to the documentation (and I dislike doing so).
Even then, you can kill a lot of seemingly inevitable interface complexity by thoughtful application of common idioms, hiding elements (ideally automatically) that are really never useful in that part of a workflow, consistent meaningful layout among work screens, communicating commonality and intent with color, proximity, shape, size, etc., good use of labels when necessary, and moderate use of animation to convey how the interface is changing so a user can stay oriented. You can really only make these decisions by carefully studying user workflows. How many enhancement request issues have you seen in issue trackers where a project maintainer makes an off-handed declaration that users don't really want/need that functionality? How often do you suppose it was entirely based on the way they use the software and nothing else?
I've spoken to many developers whose workflows have been stymied by oversimplified interfaces and they associate designers with pretty looking but defanged interfaces. Those are poorly designed interfaces. Usually they're put together by someone whose goal is to get featured on Dribbble where functionality is secondary. Those designs have their place as aesthetic inspiration for other designers, but they should not be seen as formal goals.
“Everything should be made as simple as possible, but no simpler.”
The reason why the interface design and graphic design degree programs are very similar at the college I'm attending is because many of the goals are exactly the same— using layout, text, graphics, animation, and other elements to communicate complex ideas as clearly and efficiently as possible. The semiotic analysis common in higher-level design has just as much application in interface design. The denotation of two separate save buttons might be exactly the same, the connotation might change drastically depending on what it's next to, what it's the same color of, the weight of the font, the weight of the stroke of the button compared to other elements, if there's an animation when your cursor gets close to it, etc.
Facts:
- Things like APIs and coding libraries aside, the bulk of documented interface complexity could be made obsolete in a design phase.
- Blaming users is usually what happens when developers don’t understand why their software is poorly designed.
- Most open source software doesn’t even have a design phase— it just gets built, and the warts get documented… hopefully. And if those warts change, the docs get updated… hopefully. Also, documentation is difficult to write, especially for a non-developer audience. Companies that make products with unavoidable complex interfaces or configurations have departments of technical writers who do nothing but build and refine documentation. Most of what developers consider to be carelessness in reading docs is really poorly written or constructed docs.
- Because of that, reading technical documentation is a skill. Remember the first time you looked at a man page? When you did that, you were probably vastly more technical than a typical end user. Technical documentation is just opaque to most users.
- Most end user focused commercial software is barely documented because it doesn’t need to be. Most end users wouldn’t even think to consult documentation, let alone know how to find documentation. Hell, even in the 90s the very first thing people threw away was the booklet that came with the CD ROM.
- FOSS developers embracing design knowledge can bring FOSS software to a commercial level of usability, which will vastly increase adoption. That alone is a worthy goal.
Nobody has the right to demand anything of anybody who’s volunteering their time. Never said they did. But we who develop FOSS should view usability and interface concerns just as seriously as technical concerns.
I've seen many stewards of FOSS projects treat non-blocking but ugly interface bugs as high priority issues, but terrible interfaces, workflows, wording, etc. as documentation problems or back burner issues that stay open forever.
I think it's a "when you're a hammer, everything looks like a nail" problem. Devs understand interface bugs because there's a logical difference between bug-free and buggy code. Design isn't that cut-and-dried. No matter how many times people try to quantify terrible workflow to get some sort of Big O metric— number of clicks/screens, amount of scrolling, et. al. it crumbles in opposition to empirical research. Justifying your design decisions with user research is much more difficult with open source projects, so you've really got to take the word of someone with that domain-specific interface design knowledge.
But it's important not to let these problems languish. People love the familiar— when maintainers and core users imbue their workflows with mitigation strategies, they view fixes with skepticism or even hostility. Once significant functionality gets piled on that flawed base, the chance of ever having a good, usable interface is pretty much nil.
Because the CLI is actually terrible, to the point that academic papers have been written about its terribleness. An intro guide doesn't come close to fixing any of that.
Git is the only context I’ve heard the term “porcelain” used in. A lovely bit of jargon that as far as I can tell is a more humane interface over a non-humane one.
It’s not clear to me which came first: people trying to improve the Git experience by creating porcelain, or the Git project itself distinguishing “porcelain” commands from “plumbing” commands.
I am not sure what you mean by "never mentions their existence", they are very clearly mentioned near the top of the git man page:
DESCRIPTION
Git is a fast, scalable, distributed revision control system with an
unusually rich command set that provides both high-level operations and
full access to internals.
See gittutorial(7) to get started, then see giteveryday(7) for a useful
minimum set of commands. The Git User's Manual[1] has a more in-depth
introduction.
After you mastered the basic concepts, you can come back to this page
to learn what commands Git offers. You can learn more about individual
Git commands with "git help command". gitcli(7) manual page gives you
an overview of the command-line command syntax.
This, exactly, is why using unix is so hard for beginners.
I vividly remember being extremely frustrated because every forum post on the topic seemed to assume you understood what they were asking you to do.
Man pages can be read by opening a terminal/console window and typing in ‘man [command]’, then pressing enter. Generally you can scroll through them with up/down arrow and pgup/down.
Normally the man page name is the same as the command, so I’m not sure how anyone would discover the one for gittutorial.
> Generally you can scroll through them with up/down arrow and pgup/down.
Or even your scroll wheel! :D
> Normally the man page name is the same as the command, so I’m not sure how anyone would discover the one for gittutorial.
At the bottom of every man page there is a SEE ALSO section:
SEE ALSO
gittutorial(7), gittutorial-2(7), giteveryday(7), gitcvs-migration(7), gitglossary(7), gitcore-tutorial(7), gitcli(7), The Git User’s Manual[1], gitworkflows(7)
This is as close to clickable links as man gets; if you want actual links you could run “info git” instead. There is also occasionally a NOTES section:
NOTES
1. Git User’s Manual
file:///usr/share/doc/git/user-manual.html
2. Trace2 documentation
file:///usr/share/doc/git/technical/api-trace2.html
3. Git concepts chapter of the user-manual
file:///usr/share/doc/git/user-manual.html#git-concepts
4. howto
file:///usr/share/doc/git/howto-index.html
5. Git API documentation
file:///usr/share/doc/git/technical/api-index.html
It also happens to mention gittutorial(7) and giteveryday(7) in the second sentence of the description, way back at the top of the man page. These are above the fold even in an 80×24 terminal.
If you can type “git” at a command–line prompt then you should also be able to type “man” at the same prompt.
But even if you cannot (for some unfathomable reason) git has you covered. You can type “git help foo” to open git’s man page for foo. So “git help tutorial” or “git help gittutorial” will both work.
Man pages are something that UNIX really did right. When you bought a UNIX, it came with many volumes of printed reference materials covering every detail. Every command you could type, every C library function you could call, every syscall, was documented right there in the manual on your shelf.
But they went one step further and provided the source for those manuals on the computer itself (literally, they were printed from the same troff files that the man viewer displays to you), so that you could view anything in those manuals without even taking them down off of your shelf. They’re indexed for instant retrieval and fast searches, so that there’s literally no delay when you ask for help. And they’re usually really high quality too! Sometimes they delve into jargon, or fail to spell out all of the consequences of some obscure option, but it is super rare that they leave anything out. Originally they were maintained by professional documentation writers, but these days they are lovingly maintained by volunteers who spend thousands of hours keeping them up to date.
There’s a whole education’s worth of material in there, and people just don’t use them. I can only blame learned helplessness, or Windows.
Yes, you can type "man" at a powershell prompt, but it's not an incarnation of man that knows anything about git, despite the limits of what you're able to fathom.
PS C:\> git --version
git version 2.32.0.windows.2
PS C:\> man git
Get-Help : Get-Help could not find git in a help file in this session. To download updated help topics type:
"Update-Help". To get help online, search for the help topic in the TechNet library at
https:/go.microsoft.com/fwlink/?LinkID=107116.
I use `git help` regularly. I always pass it a git command. I didn't know there were other topics you can pass.
I do know about "Info", in several contexts. Foremost, it's short for "information". But I bet that's not what you're talking about. Trying to run it yields "info : The term 'info' is not recognized as..." and so on.
Oh, I have another question or two if you have a spare moment.
Have you ever used the SEE ALSO section in the git man pages to find related information? Could you have missed the links to non–commands merely because you already knew some git commands, so you never ran “git help” without one and thus you never saw the links to the tutorial? Or is there some other cause?
Incidentally, info is a different way to read documentation, one incorporating hyperlinks and a much more book–like organizational system of chapters, sections, etc. It’s a better way to document really large programs like Emacs. It’s available on most OSes, except apparently yours, and like man it allows applications to install their own documentation. It can also read man pages; it doesn’t change them very much (they don’t have chapters, for example), but it does turn references to other man pages into actual links.
I'm not sure if you're counting "git help" as being man pages. I use "git help", but never had much use for "man"-anything. The "git help" I get already has hyperlinks, as it's literally html documents opened in a browser. Some of the documents have a "see also" section at the end. I rarely get that far though, as I tend to read just as far as I need to solve the problem at hand.
The vast majority of people have not heard of man pages, and won't at all be excited or thrilled when you tell them about them. People want to use their computer, not learn how it works. People want to be able to accomplish simple tasks without having to absorb a textbook first.
The first one, as other people have already brought up, is that looking through man pages is not the natural entry point for most users.
The second factor is that having some good help doesn't excuse the poor quality of most of the rest of the help. It's notable that you don't refer to the "git glossary" as a good entrypoint, especially since (given the next factor I'm about to elaborate), it really ought to be a useful companion. Instead, every time I try to look something up in the git glossary, I somehow end up even more confused than when I started--the help there is literally the opposite of helpful.
The third factor is the worst problem with the help: it's absolutely laden with confusing jargon. An example I easily recall is that the "staging area"--the name by which it's pretty universally known to users, in my experience--is almost universally referred to as the "index" in git's documentation, and almost nowhere else is it referred to as that. Index is a particularly bad term in this case because, if I were to list the things in a version control system I might wish to build indexes of, the changes that are being staged for a commit yet to come is not going to rank very high.
The final factor is that the poor structure of the git CLI system means that you have to rely on the help. It's notable that the poor CLI of git keeps coming up in discussions about it, far more than any other tool I've ever seen--I can't recall any complaints about any other VCS's CLI, even accounting for their collective (now) lesser popularity. It is pretty clearly objectively bad.
A great example that combines many of these points is 'git reset.' Looking at the help documentation, in the opening paragraph:
In the first three forms, copy entries from <tree-ish> to the index. In
the last form, set the current branch head (HEAD) to <commit>,
optionally modifying index and working tree to match. The
<tree-ish>/<commit> defaults to HEAD in all forms.
It outright starts by admitting that it does different things depending on how its invoked. The help immediately launches into jargon--what is a <tree-ish>? what is the index? If I'm trying to figure out how to do something--say get an older version of a file--this doesn't immediately jump out at me as being what I want...nor does it jump out as not being what I want.
I could try laboring through the help here... or I can give up, search the internet for "git get older version of a file" and be reasonably confident that I will get an answer to my question, since somebody has likely asked my question with almost exactly the words I used. And when I choose the latter method, like so many users do, git becomes a list of canned commands that are risky to venture beyond, for if I do, I run the risk of losing data, especially because operations that might repair the repository are not going to be on that list.
After finally reading about how git works internally, I can sort of see how someone that made it would write their man pages like that. With understanding of the internals it makes perfect sense.
But barely anybody that uses git cares about it’s internals.
> 'man' is not recognized as an internal or external command, operable program or batch file.
...which doesn't exist on Windows. So, are Windows git users are all doomed? Or should all Windows users download WSL in order to access this sacred tutorial?
I never bothered typing 'man git' because git offers the 'git help' workflow quite prominently with with quite satisfying results. 'git help everyday' even works, it just doesn't seem to be called out anywhere.
I was poking through the UI, but the description of "show hashes removed branch or other git objects" is ungrammatical and basically incomprehensible.
Additionally I think having two columns so I can see all options without having to open a drop-down menu (which closes and hides the list on click) would allow exploring the choices faster.
I feel like this requires you to already know what all the terminology means and how it translates into commit node manipulation, in which case you don't need something like this. Ex. "cherry-pick" and "bisect" mean very specific things in git that are not obvious.
In my experience I understand trees and nodes and how they relate to commits, and I understand the operation I want to carry out on them in terms of trees, I just don't know what git calls it. So I think it would be more useful if it described common desired operations in git-agnostic terms, and then gave me the git command to do that.
About the same functionality, made at about the same time, with an interface made for humans. It's a pity it had to compete with Linus' brand recognition.
I eventually switched from Mercurial to Git. The problem is Mercurial is too similar to SVN. All (almost) of the problems I had with SVN I still had with Mercurial.
Git is extremely hard to get into, but once you get it you can do anything you want.
Are there any good CLI wrappers over Git that make it more accessible and consistent? The only one I know of it Gitless and it looks like development on that has stopped. (Also I don't know if it's actually considered good)
It seems that git(1) was never supposed to be the be-all-end-all regular interface to Git. Other programs were developed alongside it (probably using git(1) under the hood). But they eventually faded into relative obscurity as git(1) grew larger and larger.
It’s a catch-22 with programs like git(1):
1. Make a program that is feature-rich and non-opinionated, so you really need to know what you are doing (since the program won’t help you terribly much -- oh you want a DAG, here’s some operations on DAGs... have fun)
2. Become entrenched
3. Now the average developer has to invest so much time in the UI of (1) (because it’s so feature-rich and non-opinionated) that they don’t want to also learn other frontends to it; it’s too much effort
That's my understanding of the intentions of git too. The intent seemed to be to have multiple porcelains over the same plumbing. That's why it bothers me when people talk about the default git CLI as if it's the only correct way to work with git and that we're intended to fully grok the underlying representation.
I understand plenty about the internals of git, but I still don't want to think about that when I'm just trying to version control my code. Especially because knowing any of that doesn't help me remember the many inconsistent combinations of commands and switches that actually cause various updates to the states of the graph and the pointers.
Something like this but for git plumbing would be really. Just some way of connecting low level concepts with discovering their corresponding commands.
