> Error: EPERM - Invalid permissions on myfile.out
> Cannot write to myfile.out, file does not have write permissions
> Fix with: chmod +w myfile.out
I actually much prefer:
"can't write myfile.out: Permission denied"
This shows the same information as the first 2 lines combined from the example, and the 3rd line is not necessarily the correct way to fix the problem anyway (e.g. you might be running it as your user when it should be root, chmod +w would not help).
If you are so convinced that chmod +w is the way to fix the problem, why not just do that and carry on without bugging the user?
And having each error confined to one line also means it's much less likely that some of the lines are missed, e.g. when grepping a log.
EDIT: And to add to this: it's sometimes useful to prefix the error messages with the name of the program that generated them, so that when you're looking at a combined log from different places, you know which of the programs actually wrote the error, e.g. "mycli: can't write myfile.out: Permission denied".
So, I understand the basis of your comment. You have the knowledge to know that there are other things that may be "the right way" given your situation. I think what the author is getting at is that there are users who don't have that knowledge. Giving them a hint that is verbose and non arcane can make a world of difference.
Speaking from personal experience, there are many developers that I have met who don't have basic *nix knowledge, much less knowledge of a terminal. The reality of the situation is that a business is going to hire people regardless of that ability. They want someone who can move the features out the door. Whether this is good or bad is probably beyond this conversation. I think, for those users, these sorts of helpful hints are extremely important because it makes them feel like they aren't stuck and helpless.
I think that, to your point, it may be useful to have the CLI offer a "pro" mode in which you could set a config to not give you as verbose error messages. Annoying? Yes. However, it would strike a balance and serve both needs.
Then again, on a recent linux system, the non-ability to write to the file might be permissions. Or an immutable attr, or selinux, or apparmor, or setfacl flags or a RO mount where it lies. As soon as you decide to print out the solution to "can't write to: X" you are in for a page full of advice on what to look for. Perhaps the disk was full, perhaps uid was wrong, perhaps the 5% reserved-for-root-only kicked in.
You'd end up writing a unix sysadmin guide, and then perhaps the parent dir had too strict perms to allow you to write to a file in it...
Also, on an unrelated note, I would never ever suggest novice users to blindly just give `chmod +w` to random locations. This is only marginally better than the `chmod 777 <root-folder-name>` that used to be so spread out in many (e.g. PHP-related) tutorials a decade or two ago.
Agreed, though perhaps it is just a bad example. I could imagine a situation where a single line of advice could be useful outside the realm of filesystem security or disk usage.
I understand what you're saying, but this conversation is about the best way to design CLIs.
I agree that you can do lots of stuff suboptimally and still have a usable tool, but I disagree with the author on what the ideal error output looks like.
In practice, "being verbose" is usually the opposite of "human friendly". I much prefer a spot-on one-line error message over dozens of lines of logs with an error somewhere hidden in them. Verbose error messages usually mean that you didn't have time to design succinct ones.
It's worth considering the source of this advice. Heroku is a service for which a major customer segment is people who are not adept with unix. A large part of Heroku's power, and success, comes from the fact that it makes it really easy to do things without understand everything that's going on under the hood.
Yes, this is a clear break with the unix tradition! But it's not intrinsically bad - it's just a context to bear in mind.
A few things to unpack here. First, this is just an example. A real world scenario would be something domain specific. Maybe I could come up with a better contrived example here.
Still, conceivably the app could check the file owner before showing the message. If it was a common enough error, it might be useful to do something like this.
There is a difference between an error title and error description. The description can and should be long to help clarify what is wrong. It's ok to be verbose. It's ok to spill out on multiple lines. You're much more likely to be helpful to a confused user than someone grepping logs and looking for terse output on a single line. That user can just use `grep -C` anyways.
I agree that it's useful to include the app name though.
The example provides the same error information three times ("EPERM", "Invalid permissions on myfile.out", "Cannot write to myfile.out, file does not have write permissions"), followed by a recommendation that might not be correct.
Yes, this is an example, but surely you'd want an example that shows the strength of doing this verbosely? A good example of a verbose error message system is Rust's compiler output (or newer clang/gcc outputs). Being verbose for no reason other than to be verbose is just wasting the users' time (or they just ignore the spam -- which is what I would do if I used a tool that spammed me with multiple lines of output whenever it hit an -EPERM).
Personally, something like:
% foo ./bar
foo: write config to "./bar": Permission denied
Is clearer to me than your example. Maybe something like
% foo ./bar
foo: write config to "./bar": Permission denied
Hint: Have you tried <possible-recommendation>?
Is sometimes okay (and I have done this for my own projects as well), but it's something that should be done in moderation...
> You're much more likely to be helpful to a confused user than someone grepping logs and looking for terse output on a single line.
There are two sides to this. Outputting lots of text can also cause a user to get confused (if we're talking about making things easy for not-necessarily-technical users).
When teaching (high-school) students to program, we quickly learned that even somewhat verbose output like Python's stacktraces can cause students to suddenly become anxious because there's a pile of text on their screen telling them they did something wrong. Adding more text to output does not always help, and you should keep that in mind.
IBM does that, some ANS4543 code that is the real error, _then_ a possibly translated-to-your-language error sentence that tries to help you, but if it isn't enough, you google for the error code and can potentially find help regardless of what language the blog post is in, or the forum link or whatever.
Indeed, on OS/2 one didn't google for the error code. One used the HELP command, one of whose modes of operation was looking up and printing the short and long message texts for such codes. The latter would often contain both EXPLANATION and ACTION parts.
[C:\]help sys0003
SYS0003: The system cannot find the path specified.
EXPLANATION: The path named in the command does not
exist for the drive specified or the path was
entered incorrectly.
[C:\]help sys0002
SYS0002: The system cannot find the file specified.
Explanation: The filename is incorrect or does not exist.
Action: Check the filename and retry the command.
> Cannot write to myfile.out, file does not have write permissions
> Fix with: chmod +w myfile.out
I actually much prefer:
"can't write myfile.out: Permission denied"
This shows the same information as the first 2 lines combined from the example, and the 3rd line is not necessarily the correct way to fix the problem anyway (e.g. you might be running it as your user when it should be root, chmod +w would not help).
If you are so convinced that chmod +w is the way to fix the problem, why not just do that and carry on without bugging the user?
And having each error confined to one line also means it's much less likely that some of the lines are missed, e.g. when grepping a log.
EDIT: And to add to this: it's sometimes useful to prefix the error messages with the name of the program that generated them, so that when you're looking at a combined log from different places, you know which of the programs actually wrote the error, e.g. "mycli: can't write myfile.out: Permission denied".