Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

CLI Guidelines – A guide to help you write better command-line programs

clig.dev

Post reply on HN
Print view View original

121–130 of 217 posts

Re: CLI Guidelines – A guide to help you write better command-line programs

#121

Post by lokedhs »

antientropic wrote: post #118
lokedhs wrote: post #108

Earlier quoted context omitted.

No, please don't use escape codes in your output. Use the library that is designed for this purpose: terminfo. Explicit escape codes is problematic when using any terminal that isnt' fully compatible with the xterm control codes, and doesn't allow me to turn those codes off by setting TERM to dumb. Far too many times have I redirected output from a program to a file only be be bombarded with escape codes, breaking gr…

No, don't bother with terminfo. It just gives you support for terminals that haven't been in use since the Apollo program. Nowadays it's perfectly fine to use ANSI escapes directly, which are, after all, a standard.

At the very least, use isatty() to check whether the output is actually to a terminal before polluting the log files.

Re: CLI Guidelines – A guide to help you write better command-line programs

#122

Post by djrhails »

blt wrote: post #95

This is a great resource. I will return to read it closely next time I am designing a CLI. One thing that puzzled me: `git push` is given as an example of the principle "If you change state, tell the user". Its output is: $ git push Enumerating objects: 18, done. Counting objects: 100% (18/18), done. Delta compression using up to 8 threads Compressing objects: 100% (10/10), done. Writing objects: 100% (10/10), 2.09 K…

I think the problem with this approach is when you start to utilise large (normally mono) repos the earlier stages can take significant time.

Then you're in a condumdrum of if you make the loading more generic or have an input lag to get to "writing objects".

Re: CLI Guidelines – A guide to help you write better command-line programs

#123

Post by jooize »

klodolph wrote: post #41

I think we should abolish different prefixes for short/long flags except for core POSIX programs (like ls, cp, rm, mkdir, etc.) In other words, "-flag" should be interchangeable with "-flag". The ONLY reason I can think of why you would not recognize "-flag" as equal to "--flag" is because you want to recognize it as "-f -l -a -g", which makes sense for programs like ls, but for 99% of newer programs, don’t do it. Ju…

Strongly disagree. Be consistent, avoid ambiguity, reduce risk of uncertainty. The convention has the feature of combining flags, but there's more. Making -flag and --flag equivalent means combining flags is not possible without potential collisions, and the distinction would become less obvious overall. Usage in practice would be split between -flag and --flag. Enable such inconsistency for what benefits?

Re: CLI Guidelines – A guide to help you write better command-line programs

#124

Post by tpoacher »

brabel wrote: post #107
tpoacher wrote: post #55

> "Don’t bother with man pages. [...] Not enough people use man pages [...] your time is best spent improving web docs and built-in help text." I couldn't disagree more.

You couldn't disagree that "not enough people use man pages"? Do you have a source for that belief? It's really weird to me that a few people here seem to really like their man page... when you can just do `cmd --help` and it works in pretty much any program, and you can visit the website for in-depth information.

To be fair, it depends on your exact definition of manpages, which is not clear from the article.

If by "manpages" you mean locally stored documentation which goes beyond the simple usage and available options that you'd expect from a --help switch, then I completely disagree. I believe locally available documentation in an easily accessible form and compatible with a terminal is a must.

If by "manpages" you mean specifically "it needs to be generated via groff or troff or whatever it is that generates a manpage, and is specifically for use with `man`", then fine, I can see the point. But the rebuttal here wouldn't be "because webdocs are better", and it certainly wouldn't be "because you can always bloat your --help switch to dump a mountain of text". If you have another structured way of delivering local documentation for your project, then so be it (tex does this with texdoc for instance).

Having said that, as far as standards go for local documentation with a useful and consistent structure and interface, manpages is definitely #1 and worth considering in your project, and most definitely before "webdocs".

Re: CLI Guidelines – A guide to help you write better command-line programs

#125

Post by enedil »

btschaegg wrote: post #112
throwaway201103 wrote: post #73

Earlier quoted context omitted.

Your CLI should also have a man page, installed in the standard way. IMO, -? or --help should be fairly terse, ideally one screenful or less. More complete documentation should go in the man page. Edit: wrote this before I read "Don’t bother with man pages." Strongly disagree. Relying on web docs leaves your users in the lurch if they are working on a system with no external network.

While I regularly rely on `man` (and would agree with you for systems that have it), I'd also like to add that you should consider people on other systems, as well. I'm still stuck on Windows for work, and e.g. the way Git (at least the Windows version from git-scm.org) handles this is problematic. Something like `git --help` will open the URL to a help page (that also takes ages to load) in the browser. Manpages don…

Pandoc has the ability to output manpages from .md or .rst documents, so if you already have a web version rendered from those, I see no reason not to include them. I absolutely love software with manpages and leaving them alone just because other platforms (or simply just Windows) don't have them is a bit of an insult.

Re: CLI Guidelines – A guide to help you write better command-line programs

#126

Post by klodolph »

jooize wrote: post #123
klodolph wrote: post #41

I think we should abolish different prefixes for short/long flags except for core POSIX programs (like ls, cp, rm, mkdir, etc.) In other words, "-flag" should be interchangeable with "-flag". The ONLY reason I can think of why you would not recognize "-flag" as equal to "--flag" is because you want to recognize it as "-f -l -a -g", which makes sense for programs like ls, but for 99% of newer programs, don’t do it. Ju…

Strongly disagree. Be consistent, avoid ambiguity, reduce risk of uncertainty. The convention has the feature of combining flags, but there's more. Making -flag and --flag equivalent means combining flags is not possible without potential collisions, and the distinction would become less obvious overall. Usage in practice would be split between -flag and --flag. Enable such inconsistency for what benefits?

Yes, I agree… be consistent and avoid ambiguity. Combined short flags are the most ambiguous of all.

Usage in practice would be split between -flag and --flag… so what? They shouldn’t mean different things, because it is too easy for humans to miss the extra -. And in the end, CLIs are for humans first.

Re: CLI Guidelines – A guide to help you write better command-line programs

#127

Post by enedil »

brabel wrote: post #107
tpoacher wrote: post #55

> "Don’t bother with man pages. [...] Not enough people use man pages [...] your time is best spent improving web docs and built-in help text." I couldn't disagree more.

You couldn't disagree that "not enough people use man pages"? Do you have a source for that belief? It's really weird to me that a few people here seem to really like their man page... when you can just do `cmd --help` and it works in pretty much any program, and you can visit the website for in-depth information.

"Do you have a source for that belief?" - well, you have this HN thread where about half of the comments speak about why the man pages should stay. You can find great arguments, for instance man pages are searchable inside, but also you can search for manpages containing given keywords (man -k). My shell (fish) autocompletes man pages: when I enter `man gi`, it tells me that I can see the git manual, or for instance, GIMP manual. The first thing I do with a program is to open its manpage. When it isn't available, all I can think is that it was written carelessly. If you want to have interoperable software, you absolutely need to provide manpages.

Re: CLI Guidelines – A guide to help you write better command-line programs

#128

Post by Asooka »

kitotik wrote: post #16

This is a great resource, thanks for the effort. I strongly disagree with the “ Don’t bother with man pages” advice. It’s extremely annoying when tools don’t provide a manpage. The overhead of opening up a browser to reference command is cumbersome and highly annoying. There are tools such as pandoc that make generating manpages from various source formats very easy. Perhaps it is just my grouchy old man syndrome…

Also manpages are hyperlinked to each other. You can easily say "see some other page (3)" and an html viewer will automatically make that into a hyperlink. Try the man: protocol in Konqueror. They are an extremely useful resource where you can put a lot more information than in the output of "-h".

Re: CLI Guidelines – A guide to help you write better command-line programs

#129

Post by klodolph »

attractivechaos wrote: post #42
klodolph wrote: post #41

I think we should abolish different prefixes for short/long flags except for core POSIX programs (like ls, cp, rm, mkdir, etc.) In other words, "-flag" should be interchangeable with "-flag". The ONLY reason I can think of why you would not recognize "-flag" as equal to "--flag" is because you want to recognize it as "-f -l -a -g", which makes sense for programs like ls, but for 99% of newer programs, don’t do it. Ju…

> for 99% of newer programs, don’t do it The majority of recent tools in my circle follow this Unix convention. That is a natural result when you use getopt_long().

Right, "don't do it" is imperative mood, not indicative mood. If it were indicative mood, the clause would need a subject but in a casual internet forum I can see why people would omit the subject anyway ¯\_(ツ)_/¯

This is one of the reasons why I don't use getopt_long() -- I don't WANT short flags to be combined, for most commands I write. Fortunately, getopt_long() is one of those library functions that is truly trivial to reimplement and not something that has arcane behavior or edge cases.

Re: CLI Guidelines – A guide to help you write better command-line programs

#130

Post by mcgrath_sh »

RMPR wrote: post #83
trasz wrote: post #61

Earlier quoted context omitted.

Thing is, being able to concatenate options together saves a lot of typing. (And honestly, —long-flags are rarely useful in practice. Unless you have no man page to figure out what the single letter options do.)

> honestly, —long-flags are rarely useful in practice. Unless you have no man page to figure out what the single letter options do I agree for the general case: typing commands in a terminal. But I often use long flags in scripts to improve readability.

I do the same, along with longer variable names. Every time I went back to look at old code, I am so grateful that I used the more descriptive information.
Post reply on HN