7 ms·

Pretty much each point raised in this post(?) are correct, current and relevant even 26 years later. POSIX is a monolith and really deserves to be improved. It

Pretty much each point raised in this post(?) are correct, current and relevant even 26 years later. POSIX is a monolith and really deserves to be improved. It's been around forever, yes. It will probably keep on being around forever, yes. Take the tar command (please!), which is already a nightmare where lower-case `a' means "check first" and upper-case `A' means "delete all my disk files without asking" (or something like that --- I may not have the details exactly right). In some versions of tar these meanings are reversed. This is a virtue? Raise your hand if you've never broken Grep because the flags you gave it didn't work. Anyone? Congratulations, you've worked on a single version of grep your entire life. Have a cookie. Pretty much the only consistent grep flag I know is -i. There's never been a standard for naming and abbreviating flags, which means that for EACH program you will have to learn new flags. This becomes truly terrible when you get around to, say, git and iptables. Have you ever tried to read git documentation? It is the most useless godawful piece of nonsense this side of the Moon. There's Google now, which means that the fundamental design issues of POSIX will probably never get issued. "Just google it and paste in from stackoverflow" is already standard, and people are already doing that for 5-10-year-old code/shell commands. What about 10 years from now, will googling best DHCP practices still find that stupid post from 2008 that never got actually resolved? How about 20 years? I have honestly no idea how to even start fixing the problem. A proper documentation system would be a start.

macdice 6y ago
> POSIX is a monolith and really deserves to be improved. I want it to be improved but I fear it is becoming irrelevant. There are very few OSes left to be compatible with...
- fouc 6y ago
  It's depressing to think that the Cambrian explosion that lead to a variety of hardware, software, operating systems, and web browsers and great freedom and power for the end user is gradually getting culled and turning into a monoculture of walled gardens and the end users are just getting screwed.
  - 411111111111111 6y ago
    Linux is considered a walled garden? Really? I mean yeah, there were more operating systems before, some of which were open.. but I'm not convinced it's necessarily bad to have one open system win. If it didn't, I'm pretty sure there would be a lot more people using windows servers, which I think would've been far worse for the open community.
    - AnIdiotOnTheNet 6y ago
      > Linux is considered a walled garden? Really? Kinda, yeah. At least in the Desktop space it seems like it desperately wants to be and Canonical in particular works to push it in that direction. For instance, it is highly discouraged to install software from outside your distro's repository.
      - _emacsomancer_ 6y ago
        Talking about Canonical (which advocates Snaps as a supplement to the distro's repo) and "it is highly discouraged to install software from outside your distro's repository" in the same breath is rather odd. As is thinking that Linux of all OSes is in any way a walled garden.
        deleted 6y ago
        [deleted]
        AnIdiotOnTheNet 6y ago
        Snap is very canonical centric. You cannot set up your own snap store, automatic updates are mandatory, etc. It's is for all intents and purposes a second Ubuntu repo with even stricter control.
        _emacsomancer_ 6y ago
        Multiple repos using different applications then. And the general proliferation of Appimages, Flatpak, Nix, Guix, Docker containers, and of course local building of software all tell against the "using software from outside the distro's repos is discouraged" representation.
ahartmetz 6y ago
Two points about bad documentation: The documentation (and syntax, or lack thereof) of "tc" are significantly worse than git's. Unfortunately, the network management tool you are supposed to use these days, ip, is made by the same people, though somewhat less bad. Second, take git documentation with humor: https://git-man-page-generator.lokaltog.net/ https://git-man-page-generator.lokaltog.net/
arexxbifs 6y ago
Completely agree. One of the problems is of course the freedom of choice a Unix system gives you. Instead of a single shell with a single set of commands, people can pick and mix. For beginners it's a nightmare but for power users it's, in general, very empowering. Getting help on Unix commands, particularly in Linux, has always been a mess. On most Linux distros, typing "help" will give you help about the shell built-ins. Then, discovering "man", you soon find that the bundled GNU utils of course would rather you use their "info" system, which in turn may refer to a web page(!) for info. I remember coming from the Amiga to Linux: I would not have gotten far without word-of-mouth help (and helpful computer magazine articles explaining a lot of the particularities of Unix). The Amiga, on the other hand, was a cheap home computer with an exceptionally thick manual detailing every single command clearly and succinctly. The Open Group has the POSIX util spec published online[0] and also allow free downloads of it for personal use. Since I discovered it, I find myself using it much more often than man pages. I've made a little alias in bash that launches Dillo with the appropriate command page. [0] https://pubs.opengroup.org/onlinepubs/9699919799/utilities/contents.html https://pubs.opengroup.org/onlinepubs/9699919799/utilities/c...
- jstimpfle 6y ago
  I didn't find it that hard. Just realize the different backgrounds and cultures that all these projects originate from. They all have their own ways of doing it. man pages work pretty well for a lot of stuff that is POSIX. C interfaces and basic CLI programs you'll all find documented in man (with documentation beyond what is specified in POSIX). The GNU folks have tried to push their info system, so maybe you'll find more details there for their commands. I guess most people use man because it's quick to access and a single page is easy to grep through. If that doesn't help, I'll just do a web search.
- einpoklum 6y ago
  > For beginners it's a nightmare I've taught undergraduate students some basic shell use for being able to compile their C programs. It's not really that bad. You have them use bash and you teach them some basic syntax and a few shell-usable programs, including man. You tell them that there is a lot of things the shell can do that we won't be discussing, so they have to be careful not use arbitrary symbols and to double-quote names. And I also tell them that bash is just one kind of shell, and that some systems have other shells by default, but we are working on a system which defaults to bash. I then tell them to check with "echo $SHELL" if they're on another system than the one we are working on, and if they don't see "/bin/bash" or "/usr/bin/bash" then they should ask someone for help. That's enough to satisfy newbies in my experience.
folbec 6y ago
The 4 things I love most in Powershell, from the point of view of a maintainer of scripts, is the relative verbosity of commands (at least I don't have to go hunting for obscure acronyms, or recursive puns such as yacc, when I read code), auto-completion an auto-documentation of scripts (when I have to change something), and object pipe (as a maintainer I hate awk and regular expressions in general). Only defect is they did not go with Yoda speak (Get-<TAB> is a much worse filter that NetA<TAB> to search for Get-NetAdapter for instance). It's still a bit green on Linux environments, but it already beats many of the alternatives.
- OldHand2018 6y ago
  You know, it's funny, the topic in this article is the forced abandonment of VMS. Microsoft at one time had a video interview on their "Virtual Academy" with one of the PowerShell creators, and he talks about how they kept trying to create a "unixy" tool for managing Windows machines, and it never felt or worked right. So then they looked at VMS and realized it was the perfect inspiration. Most of what you love about PowerShell comes from VMS.
  - WorldMaker 6y ago
    Which also shouldn't be surprising given VMS also had a huge inspiration (and some key figures) on early NT Kernel development. In some ways modern Windows is "son of VMS".
    - Gibbon1 6y ago
      Friend of mine's company guy bought because they had an Ethernet solution for VMS. The company that bought them wanted it ported to NT. He said it was 'almost trivial'
- Agenttin 6y ago
  I agree completely. Powershell is a pleasure to write in and read and the various modules for managing different services makes my life way easier. For anyone who's been put in charge of managing Zoom for their organization, may I recommend: https://github.com/JosephMcEvoy/PSZoom https://github.com/JosephMcEvoy/PSZoom
3np 6y ago
One of my pet-peeves on a similar note is the inconsistencies between different ssh commands on if it's -p or -P that signifies the target port. Apart from the obvious compatibility and legacy factor, I think a major reason is that by the time someone has both enough knowledge and experience to formulate a proper solution and have felt the pain-points, they're already deep enough that they've internalized that this is The Way It Is and are somewhat comfortable with it, those annoying flags aside. We tend to settle on the lowest common denominator, because consistency and time-to-ready trumps any actual improvements. For example, I'd so much prefer vim bindings in tmux but stopped using customizations like that completely since it turns out it's less of a hassle to just get used to the crappy standard ones instead of customizing it on every new host I start up. If you can't get your friends off Facebook, good luck getting engineers off POSIX.
- cgh 6y ago
  Argh yes, scp -P vs ssh -p. I get bitten by this regularly as we have something running on a non-standard port.
lioeters 6y ago
> Have you ever tried to read git documentation? It is the most useless godawful piece of nonsense I ran "man git" for the first time ever. https://www.man7.org/linux/man-pages/man1/git.1.html https://www.man7.org/linux/man-pages/man1/git.1.html Heey, that's actually pretty good! I don't think it's "godawful". In the second sentence it recommends starting with gittutorial and giteveryday, for a "useful minimum set of commands". https://www.man7.org/linux/man-pages/man7/gittutorial.7.html https://www.man7.org/linux/man-pages/man7/gittutorial.7.html https://www.man7.org/linux/man-pages/man7/giteveryday.7.html https://www.man7.org/linux/man-pages/man7/giteveryday.7.html I must admit, I still occasionally (regularly?) search for "magic incantations", particular combinations of flags for sed, git, rsync, etc. But the man pages are my first go-to, and they usually do the job as a proper documentation system. It's better than most software I've worked with outside (or on top) of the OS, with their ad-hoc, incomplete or outdated docs.
- FartyMcFarter 6y ago
  The issue with git is that no matter how well documented, the user interface is horribly designed. For starters, how many different things does "git checkout" do, and how many of them actually reflect an intuitive meaning of "checking out" ?
  - sirsuki 6y ago
    Is it true to think that because they made some choices early on that those choices forever blemish its value even is said choices are later addressed? Much of the complaints about checkout have been split to other commands in newer versions. Does this make Git still invalid in your opinion?
  - tomxor 6y ago
    > the user interface is horribly designed I see this type of remark against git quite often on HN and I think it's exaggerated. I agree some of the porcelain are misleading and overloaded as convenience functions such as checkout, however a decent chunk of it is inline with the underlying data structure. Nothing is perfect, and git is pretty damn good - horribly designed? no, could do with some breaking porcelain re-writes? sure.
enriquto 6y ago
> I have honestly no idea how to even start fixing the problem. A proper documentation system would be a start. Have you ever heard about OpenBSD?
sirsuki 6y ago
> There's never been a standard for naming and abbreviating flags, which means that for EACH program you will have to learn new flags. How is this different than web pages or GUI apps? Everyone is different and a button that does one thing in one app/page does something different in another. Have you tried to read GUI help files? They are written for 5 year olds and provide nothing you need as a dedicated user. Have you had to inspect the DOM of a website to try and intuit what something does it does not do? Least with command line apps usually you have a --help or man page.
- Joker_vD 6y ago
  GUIs have "discoverability" and "affordances". I've haven't read a single help file for any GUI application in 20 years (including apps on Windows, Linux, and Android) and somehow I can navigate and use them perfectly fine. That's simply impossible with CLIs, you need at least read a "How to Get Started Immediately" note.
  - AnIdiotOnTheNet 6y ago
    PowerShell does an okay job at command line discoverability in my experience. When using a cmdlet I'll think "I hope there's an argument for X" and then I can hit tab after '-' and cycle through all the available arguments. As another post mentioned, this unfortunately falls down a bit with cmdlet names themselves because they start with the verb instead of the noun: Get-<tab> isn't helpful the way NetAdapter-<tab> would be.
    - SAI_Peregrinus 6y ago
      Fish is similar in this way, if you're not on Windows and thus don't have access to PowerShell.
      - AnIdiotOnTheNet 6y ago
        PowerShell is available for Linux. There's also Elvish, Nushell, and a few other attempts in a similar vein.
doublesCs 6y ago
> POSIX is a monolith and really deserves to be improved. Care to explain what's intrinsically wrong with monoliths? I'd have thought that the most important point of a solution is whether or not it solves the problem, not the arhictecture by which it solves the problem.
- cogman10 6y ago
  I'm not sure it is a monolith. It is a set of standards and that's about it. But, as far as "what's wrong with monoliths" the biggest issue, IMO, is security. The more code you have, the more likely you are to run into security issues. By their nature, most security problems end up granting all access that a given program has. A monolith, by it's nature, usually has a LOT of permissions and a LOT of code. Of course, this only matters when security matters. If you are making an app that isn't exposed to the internet then by all means make it a monolith. Otherwise, the best thing you can do for security's sake is to push for microservices with as limited a permission set as possible. That makes it so the exposed surface area is relatively small if any one microservice is compromised. (It's about risk management). This is also why microkernels are so interesting to me. It's the same problem, a compromised kernel driver can do a whole lot of damage. So how do you solve that? By keeping the "root" kernel at a bare minimum and force drivers to run in user space as much as possible. That keeps drivers with security holes from giving an attacker full system control.
ACS_Solver 6y ago
I don't find `man git` to be bad at all. Git is complex, and its man pages do the right thing by referring to sources for basics info like giteveryday, and referring to in-depth guides as well. Individual man pages are also pretty good, see `man git-rebase`. It starts with an overall explanation of what rebase does, with examples, and then covers configuration options and flags. It's a lot of stuff, but it's pretty good as far as documentation goes. GNU packages often have documentation that's bad in the typical "Linux docs are bad" way. Try `man less`. First, it commits a grave sin in having a totally useless one-line summary, which reads "less - opposite of more". Funny, but totally useless and doesn't even remotely suggest what the command does (if you know what more is on UNIX, you surely know what less does). Or `man grep`. It's a reference page, very good for knowing what all the options do, but with no useful everyday examples, and with gems like these: > Finally, certain named classes of characters are predefined within bracket expressions, as follows. Their names are self explanatory, and they are [:alnum:], [:alpha:], [:cntrl:], [:digit:], [:graph:], [:lower:], [:print:], [:punct:], [:space:], [:upper:], and [:xdigit:]. Self explanatory? Yes, if you used grep in the 90s. Is alnum alphanumeric or all numbers? Is alpha short for alphabet, as in what most people would intuitively call letters? What's xdigit? Extra digits? Except digits? Oh, it's hex digits. Pretty obvious that periods and commas are in punct... but also + * - {} are punct, among other stuff. `man tar` is extremely comprehensive, an impressive reference, but very hard to figure out if you've never used tar. I've been recently looking at FreeBSD documentation for common commands, and the source code as well. Both are so much better than the usual GNU versions you find on Linux.
- jcranmer 6y ago
  > I don't find `man git` to be bad at all. Git is complex, and its man pages do the right thing by referring to sources for basics info like giteveryday, and referring to in-depth guides as well. Individual man pages are also pretty good, see `man git-rebase`. It starts with an overall explanation of what rebase does, with examples, and then covers configuration options and flags. It's a lot of stuff, but it's pretty good as far as documentation goes. Having used both Mercurial and git, it is my general experience that Mercurial has a much better documentation system. Git's documentation has improved, but mostly only in the more-well-used commands; when you want to reach for more exotic stuff, you start to find that the documentation is too full of jargon. As a recent example, I wanted to get a list of files managed by git. Since I know mercurial best, I wanted the equivalent of hg manifest. Its documentation is thus: > hg manifest [-r REV] > output the current or given revision of the project manifest > Print a list of version controlled files for the given revision. If no revision is given, the first parent of the working directory is used, or the null revision if no revision is checked out. This is unusually bad documentation for mercurial--the short description and command name are reliant on jargon, and it's not aliased to "hg ls" or something like that. Okay, how about the equivalent git command? git ls-files looks promising. Here's its short description: > git-ls-files - Show information about files in the index and the working tree But its description is, um: > This merges the file listing in the directory cache index with the actual working directory list, and shows different combinations of the two. Mercurial suffers from a bit of jargon, but reading its description would enlighten you as to what it does without understanding the jargon. Git's documentation here starts with jargon, and then doubles down on it so that the more I read, the less sure I am about what it actually does. [In the end, by actually running it, I did verify that it's basically the equivalent of hg manifest]. Now both mercurial and git have a glossary (help glossary), but I've never seen anyone actually point a newbie to either one. Of course, here you can also see the world of difference in the documentation quality. Mercurial's glossary entry for the jargon term "manifest" says: > Each changeset has a manifest, which is the list of files that are tracked by the changeset. Now compare git's glossary entry for "index": > A collection of files with stat information, whose contents are stored as objects. The index is a stored version of your working tree. Truth be told, it can also contain a second, and even a third version of a working tree, which are used when merging. ... and that is why people like me say that git suffers from poor documentation.
kazinator 6y ago
grep was standardized around 1990 by POSIX.2. In the last 25 years, I haven't had any problems with the POSIX compatible flags of grep, so maybe those points are not so relevant. Using grep for '$' without being aware that grep patterns are regular expressions ((g)lobal search for (re)gexp, and (p)rint), and redirecting the output to the printer without first seeing what it might be (e.g. with .. | head -50) is pretty stupid. Consider that this person's idea of solving the problem of "move occurrences of $ character to a different location within the line" in a bunch of files was to begin by searching for lines containing those $ characters and sending that to a printer. What? How is the hard copy going to help? Are you going to sit there manually typing in those paths and looking for those line numbers, to do the edit? If that is really the VMS way, who wants anything to do with it?
- deleted 6y ago
  [deleted]
- rbanffy 6y ago
  > Using grep for '$' without being aware that grep patterns are regular expressions There's always `fgrep` or, IIRC, the POSIX-compliant `grep -F`. More often than not, people don't want regular expressions.
- AceyMan 6y ago
  I learned it as meaning— Global Regular Expression Parser that seemed plausible enough I never questioned it.
Aloha 6y ago
When I'm on a strange system for the first time and I need grep, the first thing I'm doing is grep --help or man grep to check to see what I'm doing with.
microtherion 6y ago
git has quite extensive documentation, and it is, in principle, really useful. The problem is that it suffers from what Geoffrey Pullum called "Nerdview" <https://languagelog.ldc.upenn.edu/nll/?p=276> https://languagelog.ldc.upenn.edu/nll/?p=276>: It is written from the perspective of the author of the program, rather than the user, and therefore it is easiest to understand if you are already thoroughly familiar with the underlying architecture of git.

macdice 6y ago

> POSIX is a monolith and really deserves to be improved. I want it to be improved but I fear it is becoming irrelevant. There are very few OSes left to be compatible with...

fouc 6y ago
It's depressing to think that the Cambrian explosion that lead to a variety of hardware, software, operating systems, and web browsers and great freedom and power for the end user is gradually getting culled and turning into a monoculture of walled gardens and the end users are just getting screwed.
- 411111111111111 6y ago
  Linux is considered a walled garden? Really? I mean yeah, there were more operating systems before, some of which were open.. but I'm not convinced it's necessarily bad to have one open system win. If it didn't, I'm pretty sure there would be a lot more people using windows servers, which I think would've been far worse for the open community.
  - AnIdiotOnTheNet 6y ago
    > Linux is considered a walled garden? Really? Kinda, yeah. At least in the Desktop space it seems like it desperately wants to be and Canonical in particular works to push it in that direction. For instance, it is highly discouraged to install software from outside your distro's repository.
    - _emacsomancer_ 6y ago
      Talking about Canonical (which advocates Snaps as a supplement to the distro's repo) and "it is highly discouraged to install software from outside your distro's repository" in the same breath is rather odd. As is thinking that Linux of all OSes is in any way a walled garden.
      - deleted 6y ago
        [deleted]
      - AnIdiotOnTheNet 6y ago
        Snap is very canonical centric. You cannot set up your own snap store, automatic updates are mandatory, etc. It's is for all intents and purposes a second Ubuntu repo with even stricter control.
        _emacsomancer_ 6y ago
        Multiple repos using different applications then. And the general proliferation of Appimages, Flatpak, Nix, Guix, Docker containers, and of course local building of software all tell against the "using software from outside the distro's repos is discouraged" representation.

ahartmetz 6y ago

Two points about bad documentation: The documentation (and syntax, or lack thereof) of "tc" are significantly worse than git's. Unfortunately, the network management tool you are supposed to use these days, ip, is made by the same people, though somewhat less bad. Second, take git documentation with humor: https://git-man-page-generator.lokaltog.net/ https://git-man-page-generator.lokaltog.net/

arexxbifs 6y ago

Completely agree. One of the problems is of course the freedom of choice a Unix system gives you. Instead of a single shell with a single set of commands, people can pick and mix. For beginners it's a nightmare but for power users it's, in general, very empowering. Getting help on Unix commands, particularly in Linux, has always been a mess. On most Linux distros, typing "help" will give you help about the shell built-ins. Then, discovering "man", you soon find that the bundled GNU utils of course would rather you use their "info" system, which in turn may refer to a web page(!) for info. I remember coming from the Amiga to Linux: I would not have gotten far without word-of-mouth help (and helpful computer magazine articles explaining a lot of the particularities of Unix). The Amiga, on the other hand, was a cheap home computer with an exceptionally thick manual detailing every single command clearly and succinctly. The Open Group has the POSIX util spec published online[0] and also allow free downloads of it for personal use. Since I discovered it, I find myself using it much more often than man pages. I've made a little alias in bash that launches Dillo with the appropriate command page. [0] https://pubs.opengroup.org/onlinepubs/9699919799/utilities/contents.html https://pubs.opengroup.org/onlinepubs/9699919799/utilities/c...

jstimpfle 6y ago
I didn't find it that hard. Just realize the different backgrounds and cultures that all these projects originate from. They all have their own ways of doing it. man pages work pretty well for a lot of stuff that is POSIX. C interfaces and basic CLI programs you'll all find documented in man (with documentation beyond what is specified in POSIX). The GNU folks have tried to push their info system, so maybe you'll find more details there for their commands. I guess most people use man because it's quick to access and a single page is easy to grep through. If that doesn't help, I'll just do a web search.
einpoklum 6y ago
> For beginners it's a nightmare I've taught undergraduate students some basic shell use for being able to compile their C programs. It's not really that bad. You have them use bash and you teach them some basic syntax and a few shell-usable programs, including man. You tell them that there is a lot of things the shell can do that we won't be discussing, so they have to be careful not use arbitrary symbols and to double-quote names. And I also tell them that bash is just one kind of shell, and that some systems have other shells by default, but we are working on a system which defaults to bash. I then tell them to check with "echo $SHELL" if they're on another system than the one we are working on, and if they don't see "/bin/bash" or "/usr/bin/bash" then they should ask someone for help. That's enough to satisfy newbies in my experience.

folbec 6y ago

The 4 things I love most in Powershell, from the point of view of a maintainer of scripts, is the relative verbosity of commands (at least I don't have to go hunting for obscure acronyms, or recursive puns such as yacc, when I read code), auto-completion an auto-documentation of scripts (when I have to change something), and object pipe (as a maintainer I hate awk and regular expressions in general). Only defect is they did not go with Yoda speak (Get-<TAB> is a much worse filter that NetA<TAB> to search for Get-NetAdapter for instance). It's still a bit green on Linux environments, but it already beats many of the alternatives.

OldHand2018 6y ago
You know, it's funny, the topic in this article is the forced abandonment of VMS. Microsoft at one time had a video interview on their "Virtual Academy" with one of the PowerShell creators, and he talks about how they kept trying to create a "unixy" tool for managing Windows machines, and it never felt or worked right. So then they looked at VMS and realized it was the perfect inspiration. Most of what you love about PowerShell comes from VMS.
- WorldMaker 6y ago
  Which also shouldn't be surprising given VMS also had a huge inspiration (and some key figures) on early NT Kernel development. In some ways modern Windows is "son of VMS".
  - Gibbon1 6y ago
    Friend of mine's company guy bought because they had an Ethernet solution for VMS. The company that bought them wanted it ported to NT. He said it was 'almost trivial'
Agenttin 6y ago
I agree completely. Powershell is a pleasure to write in and read and the various modules for managing different services makes my life way easier. For anyone who's been put in charge of managing Zoom for their organization, may I recommend: https://github.com/JosephMcEvoy/PSZoom https://github.com/JosephMcEvoy/PSZoom

3np 6y ago

One of my pet-peeves on a similar note is the inconsistencies between different ssh commands on if it's -p or -P that signifies the target port. Apart from the obvious compatibility and legacy factor, I think a major reason is that by the time someone has both enough knowledge and experience to formulate a proper solution and have felt the pain-points, they're already deep enough that they've internalized that this is The Way It Is and are somewhat comfortable with it, those annoying flags aside. We tend to settle on the lowest common denominator, because consistency and time-to-ready trumps any actual improvements. For example, I'd so much prefer vim bindings in tmux but stopped using customizations like that completely since it turns out it's less of a hassle to just get used to the crappy standard ones instead of customizing it on every new host I start up. If you can't get your friends off Facebook, good luck getting engineers off POSIX.

cgh 6y ago
Argh yes, scp -P vs ssh -p. I get bitten by this regularly as we have something running on a non-standard port.

lioeters 6y ago

> Have you ever tried to read git documentation? It is the most useless godawful piece of nonsense I ran "man git" for the first time ever. https://www.man7.org/linux/man-pages/man1/git.1.html https://www.man7.org/linux/man-pages/man1/git.1.html Heey, that's actually pretty good! I don't think it's "godawful". In the second sentence it recommends starting with gittutorial and giteveryday, for a "useful minimum set of commands". https://www.man7.org/linux/man-pages/man7/gittutorial.7.html https://www.man7.org/linux/man-pages/man7/gittutorial.7.html https://www.man7.org/linux/man-pages/man7/giteveryday.7.html https://www.man7.org/linux/man-pages/man7/giteveryday.7.html I must admit, I still occasionally (regularly?) search for "magic incantations", particular combinations of flags for sed, git, rsync, etc. But the man pages are my first go-to, and they usually do the job as a proper documentation system. It's better than most software I've worked with outside (or on top) of the OS, with their ad-hoc, incomplete or outdated docs.

FartyMcFarter 6y ago
The issue with git is that no matter how well documented, the user interface is horribly designed. For starters, how many different things does "git checkout" do, and how many of them actually reflect an intuitive meaning of "checking out" ?
- sirsuki 6y ago
  Is it true to think that because they made some choices early on that those choices forever blemish its value even is said choices are later addressed? Much of the complaints about checkout have been split to other commands in newer versions. Does this make Git still invalid in your opinion?
- tomxor 6y ago
  > the user interface is horribly designed I see this type of remark against git quite often on HN and I think it's exaggerated. I agree some of the porcelain are misleading and overloaded as convenience functions such as checkout, however a decent chunk of it is inline with the underlying data structure. Nothing is perfect, and git is pretty damn good - horribly designed? no, could do with some breaking porcelain re-writes? sure.

enriquto 6y ago

> I have honestly no idea how to even start fixing the problem. A proper documentation system would be a start. Have you ever heard about OpenBSD?

sirsuki 6y ago

> There's never been a standard for naming and abbreviating flags, which means that for EACH program you will have to learn new flags. How is this different than web pages or GUI apps? Everyone is different and a button that does one thing in one app/page does something different in another. Have you tried to read GUI help files? They are written for 5 year olds and provide nothing you need as a dedicated user. Have you had to inspect the DOM of a website to try and intuit what something does it does not do? Least with command line apps usually you have a --help or man page.

Joker_vD 6y ago
GUIs have "discoverability" and "affordances". I've haven't read a single help file for any GUI application in 20 years (including apps on Windows, Linux, and Android) and somehow I can navigate and use them perfectly fine. That's simply impossible with CLIs, you need at least read a "How to Get Started Immediately" note.
- AnIdiotOnTheNet 6y ago
  PowerShell does an okay job at command line discoverability in my experience. When using a cmdlet I'll think "I hope there's an argument for X" and then I can hit tab after '-' and cycle through all the available arguments. As another post mentioned, this unfortunately falls down a bit with cmdlet names themselves because they start with the verb instead of the noun: Get-<tab> isn't helpful the way NetAdapter-<tab> would be.
  - SAI_Peregrinus 6y ago
    Fish is similar in this way, if you're not on Windows and thus don't have access to PowerShell.
    - AnIdiotOnTheNet 6y ago
      PowerShell is available for Linux. There's also Elvish, Nushell, and a few other attempts in a similar vein.

doublesCs 6y ago

> POSIX is a monolith and really deserves to be improved. Care to explain what's intrinsically wrong with monoliths? I'd have thought that the most important point of a solution is whether or not it solves the problem, not the arhictecture by which it solves the problem.

cogman10 6y ago
I'm not sure it is a monolith. It is a set of standards and that's about it. But, as far as "what's wrong with monoliths" the biggest issue, IMO, is security. The more code you have, the more likely you are to run into security issues. By their nature, most security problems end up granting all access that a given program has. A monolith, by it's nature, usually has a LOT of permissions and a LOT of code. Of course, this only matters when security matters. If you are making an app that isn't exposed to the internet then by all means make it a monolith. Otherwise, the best thing you can do for security's sake is to push for microservices with as limited a permission set as possible. That makes it so the exposed surface area is relatively small if any one microservice is compromised. (It's about risk management). This is also why microkernels are so interesting to me. It's the same problem, a compromised kernel driver can do a whole lot of damage. So how do you solve that? By keeping the "root" kernel at a bare minimum and force drivers to run in user space as much as possible. That keeps drivers with security holes from giving an attacker full system control.

ACS_Solver 6y ago

I don't find `man git` to be bad at all. Git is complex, and its man pages do the right thing by referring to sources for basics info like giteveryday, and referring to in-depth guides as well. Individual man pages are also pretty good, see `man git-rebase`. It starts with an overall explanation of what rebase does, with examples, and then covers configuration options and flags. It's a lot of stuff, but it's pretty good as far as documentation goes. GNU packages often have documentation that's bad in the typical "Linux docs are bad" way. Try `man less`. First, it commits a grave sin in having a totally useless one-line summary, which reads "less - opposite of more". Funny, but totally useless and doesn't even remotely suggest what the command does (if you know what more is on UNIX, you surely know what less does). Or `man grep`. It's a reference page, very good for knowing what all the options do, but with no useful everyday examples, and with gems like these: > Finally, certain named classes of characters are predefined within bracket expressions, as follows. Their names are self explanatory, and they are [:alnum:], [:alpha:], [:cntrl:], [:digit:], [:graph:], [:lower:], [:print:], [:punct:], [:space:], [:upper:], and [:xdigit:]. Self explanatory? Yes, if you used grep in the 90s. Is alnum alphanumeric or all numbers? Is alpha short for alphabet, as in what most people would intuitively call letters? What's xdigit? Extra digits? Except digits? Oh, it's hex digits. Pretty obvious that periods and commas are in punct... but also + * - {} are punct, among other stuff. `man tar` is extremely comprehensive, an impressive reference, but very hard to figure out if you've never used tar. I've been recently looking at FreeBSD documentation for common commands, and the source code as well. Both are so much better than the usual GNU versions you find on Linux.

jcranmer 6y ago
> I don't find `man git` to be bad at all. Git is complex, and its man pages do the right thing by referring to sources for basics info like giteveryday, and referring to in-depth guides as well. Individual man pages are also pretty good, see `man git-rebase`. It starts with an overall explanation of what rebase does, with examples, and then covers configuration options and flags. It's a lot of stuff, but it's pretty good as far as documentation goes. Having used both Mercurial and git, it is my general experience that Mercurial has a much better documentation system. Git's documentation has improved, but mostly only in the more-well-used commands; when you want to reach for more exotic stuff, you start to find that the documentation is too full of jargon. As a recent example, I wanted to get a list of files managed by git. Since I know mercurial best, I wanted the equivalent of hg manifest. Its documentation is thus: > hg manifest [-r REV] > output the current or given revision of the project manifest > Print a list of version controlled files for the given revision. If no revision is given, the first parent of the working directory is used, or the null revision if no revision is checked out. This is unusually bad documentation for mercurial--the short description and command name are reliant on jargon, and it's not aliased to "hg ls" or something like that. Okay, how about the equivalent git command? git ls-files looks promising. Here's its short description: > git-ls-files - Show information about files in the index and the working tree But its description is, um: > This merges the file listing in the directory cache index with the actual working directory list, and shows different combinations of the two. Mercurial suffers from a bit of jargon, but reading its description would enlighten you as to what it does without understanding the jargon. Git's documentation here starts with jargon, and then doubles down on it so that the more I read, the less sure I am about what it actually does. [In the end, by actually running it, I did verify that it's basically the equivalent of hg manifest]. Now both mercurial and git have a glossary (help glossary), but I've never seen anyone actually point a newbie to either one. Of course, here you can also see the world of difference in the documentation quality. Mercurial's glossary entry for the jargon term "manifest" says: > Each changeset has a manifest, which is the list of files that are tracked by the changeset. Now compare git's glossary entry for "index": > A collection of files with stat information, whose contents are stored as objects. The index is a stored version of your working tree. Truth be told, it can also contain a second, and even a third version of a working tree, which are used when merging. ... and that is why people like me say that git suffers from poor documentation.

kazinator 6y ago

grep was standardized around 1990 by POSIX.2. In the last 25 years, I haven't had any problems with the POSIX compatible flags of grep, so maybe those points are not so relevant. Using grep for '$' without being aware that grep patterns are regular expressions ((g)lobal search for (re)gexp, and (p)rint), and redirecting the output to the printer without first seeing what it might be (e.g. with .. | head -50) is pretty stupid. Consider that this person's idea of solving the problem of "move occurrences of $ character to a different location within the line" in a bunch of files was to begin by searching for lines containing those $ characters and sending that to a printer. What? How is the hard copy going to help? Are you going to sit there manually typing in those paths and looking for those line numbers, to do the edit? If that is really the VMS way, who wants anything to do with it?

deleted 6y ago
[deleted]
rbanffy 6y ago
> Using grep for '$' without being aware that grep patterns are regular expressions There's always `fgrep` or, IIRC, the POSIX-compliant `grep -F`. More often than not, people don't want regular expressions.
AceyMan 6y ago
I learned it as meaning— Global Regular Expression Parser that seemed plausible enough I never questioned it.

Aloha 6y ago

When I'm on a strange system for the first time and I need grep, the first thing I'm doing is grep --help or man grep to check to see what I'm doing with.

microtherion 6y ago

git has quite extensive documentation, and it is, in principle, really useful. The problem is that it suffers from what Geoffrey Pullum called "Nerdview" <https://languagelog.ldc.upenn.edu/nll/?p=276> https://languagelog.ldc.upenn.edu/nll/?p=276>: It is written from the perspective of the author of the program, rather than the user, and therefore it is easiest to understand if you are already thoroughly familiar with the underlying architecture of git.