[HN Gopher] Git Command Explorer
___________________________________________________________________
Git Command Explorer
Author : MakisH
Score : 270 points
Date : 2021-10-16 15:59 UTC (1 days ago)
(HTM) web link (gitexplorer.com)
(TXT) w3m dump (gitexplorer.com)
| breakfastduck wrote:
| The typing reeks of a front end dev doing something fancy at the
| cost of UX.
|
| Like when people add artificial loading to show their really cool
| spinner.
|
| Infuriating. Have it toggle on/off not fast/slow.
| lazyant wrote:
| if this had a tree graph or visual aid for some of the commands
| that would be great
| layer8 wrote:
| It would be nice to just have a static page with all the content
| as sections and subsections.
| asimpletune wrote:
| Something like this but for git plumbing would be really. Just
| some way of connecting low level concepts with discovering their
| corresponding commands.
| vfclists wrote:
| Stop!! Stop!! Stop!!
|
| Just install Emacs and use Magit.
|
| You can still use your favourite editor and switch to Emacs for
| your commit activities. Whats there to loose.
| markussss wrote:
| 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".
| FrontAid wrote:
| bit (https://github.com/chriswalz/bit) is a somewhat similar CLI
| tool for this. It shows command completion alongside a
| description.
|
| PS: We maintain a list of helpful Git CLI tools on
| https://github.com/frontaid/git-cli-tools
| diogenesjunior wrote:
| Besides the heap of javascript, very cool.
| chenster wrote:
| Well done! Also check out Tower Git client. It has very good GUI
| that requires no terminal command.
| anotherevan wrote:
| The more I use git, the more I like mercurial.
| foresto wrote:
| 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.
| Aeolun wrote:
| 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.
| niros_valtos wrote:
| I really don't get the need for it. Open the terminal. Type "man
| git" and you're done!
| FailMore wrote:
| Remember
| sgallant wrote:
| Well done!
| laurent123456 wrote:
| 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.
| nyanpasu64 wrote:
| 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.
| octorian wrote:
| Did I miss something, or did they forget to cover "push", "pull",
| and "branch"? (and possibly a few other very common things)
| mid-kid wrote:
| 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.
| laurent92 wrote:
| The very simple fact that your GIT help command is
| unfindable/unguessable/undiscoverable is the essence, the
| succulent "aperitif" of Git.
|
| Fortunately git is majority, so it's justified to master it. I
| would not accept that from an OS, for example.
| jcranmer wrote:
| There are 4 factors.
|
| 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.
| Aeolun wrote:
| 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.
| Timwi wrote:
| I will never understand how git became the de facto standard
| when everyone can see at first glance how terrible it is.
| [deleted]
| stevage wrote:
| 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.
| WalterGR wrote:
| 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.
| recursive wrote:
| For one, git never mentions their existence. For another, now
| that I've heard of them, I still don't know how to access them.
| db48x wrote:
| Do you seriously not know how to access man pages?
| Aeolun wrote:
| 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.
| db48x wrote:
| > 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 80x24 terminal.
| recursive wrote:
| Tell me if I'm wrong.
|
| 1. Have some unix-like operating system. 2. Type `man` at a
| command prompt.
|
| Is that about right? I haven't got to step 1 yet.
| unnah wrote:
| You can also type "man gittutorial" (with or without
| quotes) on google or bing.
| mixmastamyk wrote:
| Good point. Duck duck go preferred.
| db48x wrote:
| 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.
|
| I bet you don't know about Info either.
| recursive wrote:
| 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.
| Timwi wrote:
| 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.
| b3n wrote:
| 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.
| TehCorwiz wrote:
| 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.
| chefandy wrote:
| 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
| WalterGR wrote:
| I've never heard of HFE. Is this what you're referring to?
| https://en.m.wikipedia.org/wiki/Human_factors_and_ergonomics
| yarky wrote:
| > 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.
| Aeolun wrote:
| 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).
| bluepoint wrote:
| What resources do you recommend for starting to learn more
| about design?
| kkirsche wrote:
| Git everyday's web version: https://git-
| scm.com/docs/giteveryday
|
| Git tutorial's web version: https://git-
| scm.com/docs/gittutorial
| AnIdiotOnTheNet wrote:
| And how does one discover that those exist?
| mid-kid wrote:
| "man git", second paragraph.
| sharken wrote:
| Having recently switched to Git on Windows, you miss out on
| these great resources.
|
| Thankfully with all the Git information floating around
| it's easy enough to find answers.
|
| One such page is this one containing three good tips
|
| https://spin.atomicobject.com/2020/05/05/git-
| configurations-...
| _jal wrote:
| try "man git" in your favorite search engine.
| zorr wrote:
| And if your favorite search engine is DuckDuckGo you can
| search "!man git"
| sebazzz wrote:
| Even as a Linux user I prefer online man pages for easier
| navigation.
| uuddlrlr wrote:
| Terminals generally have decent mouse support don't they?
| Maybe we ought to trick out a man reader.
| wongarsu wrote:
| 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.
| SCLeo wrote:
| > '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?
| Aeolun wrote:
| > Or should all Windows users download WSL
|
| In general, yes. That would make all our lives a _lot_
| easier. Not just in relation to git, but because everyone
| works off the same base then.
| cloakedcode wrote:
| That's fair. What environment do you have that installed
| git at the command line? I'm assuming 'git' is a
| recognized command.
| recursive wrote:
| This is the normal state of affairs after running the git
| installer from git-scm.com
| drdeca wrote:
| I've attempted to find a way to install man in git bash,
| but haven't found a simple way to do so
| spicybright wrote:
| No bisect? Or `log --graph`? Or `git rev-parse HEAD`?
|
| Idk, I use the above quite a bit myself.
|
| I wonder if it would be more useful in the reverse, where you
| click your question of what you want to do, then you get the git
| command and args.
| avgcorrection wrote:
| Bisect is under debug - binary search.
| spicybright wrote:
| Oh, just noticing there's a mix of git specific commands and
| actions a user would want to take.
|
| Like, I wouldn't know what a cherry-pick means if I didn't
| use git a lot.
| sabhiram wrote:
| this exactly :)
| teawrecks wrote:
| 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.
| overcast wrote:
| 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.
| srik wrote:
| I agree; maybe don't type the "note" at least.
| kwertyoowiyop wrote:
| Agree on the "typing." We're not watching RPG characters
| converse.
| fragmede wrote:
| contrary opinion: keep the typing. (i'd default to fast and get
| rid of the toggle though, but you didn't ask.)
| dtgriscom wrote:
| 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.
| Gehinnn wrote:
| Related: Git Line Endings configurator. Uses a github action to
| brute force all combinations.
|
| https://hediet.github.io/git-line-endings/
| sicromoft wrote:
| It's missing a few commands, like git-jolt-ancestor[1] and git-
| shout-revision[2].
|
| [1] https://git-man-page-
| generator.lokaltog.net/#am9sdCQkYW5jZXN...
|
| [2] https://git-man-page-
| generator.lokaltog.net/#c2hvdXQkJHJldml...
| advance512 wrote:
| That took me too long :)
| ziml77 wrote:
| 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)
| stevage wrote:
| There were a few. Legit was another.
| bewuethr wrote:
| Mentioned in another comment: https://qithub.com/chriswalz/bit
|
| I haven't tried it, but it looks promising.
| bewuethr wrote:
| Yikes... https://github.com/chriswalz/bit, not qithub!
| ziml77 wrote:
| Oh that one does look cool. I'll certainly be giving it a
| try.
| avgcorrection wrote:
| 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
| ziml77 wrote:
| 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.
| zeynepevecen wrote:
| This is great UI and idea! I think you can improve it with a
| search bar. It would be faster.
___________________________________________________________________
(page generated 2021-10-17 23:02 UTC)