Help Message for Shell Scripts

457 pointsby reconquestioalmost 5 years ago

25 comments

gorgoileralmost 5 years ago

The power is out on your boat, again. It’s 3am. You suspect that, again, the alternator housing has come loose.You duct tape a flashlight to the bulkhead so you can work hands free and actually see what you are doing. All you have on you is a broken pocket knife but it’ll do because all you need to accomplish right now is to tighten the housing screws enough. You know this for a fact because you’ve done it three times already in the last 24 hours.It’s not even a documented procedure — you’ll replace the housing mounts entirely when you’re back at port in three days’ time. You guarantee it — this is the first thing you’ll do even, when you get back to shore. You have my word on that, captain!The duct tape came unstuck. It was damp and doesn’t work so well (at all) when it’s wet. The flashlight survived the fall. More tape this time should do the job. Tape mount version 2 will still unstick of course, eventually. Nothing stops the damp at sea, but if you use enough tape then you’ll have fixed the power by the time the tape fails. That’s your plan B and you’re sticking to it.Sure, you could do this job better if you had an impact driver with an automatically illuminated bit chuck, but buying one of those is further down the todo list than fixing the power on the boat, making it back to port, and ensuring the power doesn’t fail this way again, as promised. Or at least won’t fail for the next few shifts.On your days off you relax by programming in Bash.

评论 #23769051 未加载

adrianmonkalmost 5 years ago

You can also use a "here document"<pre><code> help() { cat <<'EOH' my-script — does one thing well Usage: my-script <input> <output> Options: <input> Input file to read. <output> Output file to write. Use '-' for stdout. -h Show this message. EOH } </code></pre> If the indentation bugs you, you can use a simpler sed trick to remove leading space so that you can indent it as desired:<pre><code> help() { sed -e 's/ //' <<'EOH' my-script — does one thing well Usage: my-script <input> <output> Options: <input> Input file to read. <output> Output file to write. Use '-' for stdout. -h Show this message. EOH }</code></pre>

评论 #23764971 未加载

评论 #23763762 未加载

评论 #23764006 未加载

评论 #23764510 未加载

评论 #23766126 未加载

评论 #23764334 未加载

评论 #23765411 未加载

j1eloalmost 5 years ago

I learnt the same trick some years ago, from an article called Shell Scripts Matter:<a href="https://dev.to/thiht/shell-scripts-matter" rel="nofollow">https://dev.to/thiht/shell-scripts-matter</a>So I took some of the advice and tips offered in there, and wrote a template file to be used as a baseline when writing scripts for any project that might need one:<a href="https://github.com/j1elo/shell-snippets/blob/master/template.sh" rel="nofollow">https://github.com/j1elo/shell-snippets/blob/master/template...</a>Other resources that I link in the readme of that repo, because they were a great guide to write better and more robust scripts, are:- Writing Robust Bash Shell Scripts: <a href="https://www.davidpashley.com/articles/writing-robust-shell-scripts/" rel="nofollow">https://www.davidpashley.com/articles/writing-robust-shell-s...</a>- Common shell script mistakes: <a href="http://www.pixelbeat.org/programming/shell_script_mistakes.html" rel="nofollow">http://www.pixelbeat.org/programming/shell_script_mistakes.h...</a>- Bash Pitfalls: <a href="http://mywiki.wooledge.org/BashPitfalls" rel="nofollow">http://mywiki.wooledge.org/BashPitfalls</a>- The Bash Hackers Wiki: <a href="https://wiki.bash-hackers.org/" rel="nofollow">https://wiki.bash-hackers.org/</a>EDIT: -for anyone who would like to read some actual examples- I have to manage a bunch of scripts so actually a slightly more up to date version of the template is put into practice by means of a common bash.conf file that then gets sourced by all scripts: <a href="https://github.com/Kurento/adm-scripts/blob/master/bash.conf.sh" rel="nofollow">https://github.com/Kurento/adm-scripts/blob/master/bash.conf...</a>

评论 #23765680 未加载

评论 #23766134 未加载

meyalmost 5 years ago

Handling of arguments is one of the reasons I reach for Python or Powershell instead of a bash script when writing my own stuff.<a href="https://docs.python.org/3/library/argparse.html" rel="nofollow">https://docs.python.org/3/library/argparse.html</a> is great.Powershell has the Param keyword that functions like argparse in Python<a href="https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-7" rel="nofollow">https://docs.microsoft.com/en-us/powershell/module/microsoft...</a>

评论 #23764073 未加载

评论 #23763794 未加载

评论 #23765817 未加载

评论 #23764247 未加载

评论 #23774220 未加载

评论 #23764475 未加载

评论 #23763790 未加载

评论 #23764839 未加载

diablerougealmost 5 years ago

This seems like a neat sed trick, but I'm not sure that it's useful for this particular case?When I write a shell script, I often write a help function if it's not a totally trivial script, but there's no need for this cryptic sed expression, right? You can just call `echo` a few times and do it the obvious way. That works better for maintainability and if you put it at the top of the file then it's immediately visible when opening or using `head` on it.Neat trick though - sed is super useful for all kinds of things. I had a co-worker who bound a keybinding to a sed one-liner that would automagically reconfigure some files that needed to be changed regularly. I ended up using that trick to allow for changing my terminal console colorscheme with a single command.

评论 #23763572 未加载

评论 #23764742 未加载

dougdonohoealmost 5 years ago

We do this for Makefile entries - looking for '##' that we put before each make command.<pre><code> ## help: prints this help message help: @echo "Usage: \n" @egrep -h "^## [a-zA-Z0-9\-]*:" ${MAKEFILE_LIST} | sed -e 's/##//' | column -t -s ':' | sed -e 's/^/ /' ## build: builds JAR with dependencies build: mvn compile</code></pre>

xvolteralmost 5 years ago

I also posted to the github gist, this the sed command here is not cross-plataform friendly. You can accomplish the same thing with an awk command though:awk '/^###/' "$0"

评论 #23765719 未加载

评论 #23765563 未加载

评论 #23764369 未加载

评论 #23764086 未加载

account42almost 5 years ago

> $0 means a filename of a file that is being executed.This is only a convention and is entirely up to the calling program.For example in bash scripts you can use `exec -a name ...` to pass "name" as the 0th argument.If you are already using #!/bin/bash you might as well use ${BASH_SOURCE[0]} to get the path to the current script.

xelxebaralmost 5 years ago

This reminds me of a nice sed one-liner I recently happened to craft.Do you ever collect families of functions in your shell scripts under different sections? Here's a nice way of printing out all the functions under a given section:<pre><code> funs(){ sed -n '/^## /h;x;/'"$1"'/{x;s/^$\w\+$().*/\1/p;x};x' "$0";} </code></pre> Where "sections" are delimited by comments of the form "## Section Name" at the beginning of a line. A particularly nice use case is when you write scripts that expect "subcommand" arguments, like<pre><code> $ foo.sh bar baz </code></pre> and wish to keep track of the available subcommands in the help documentation. Simply collect all your subcommands under the heading "## Subcommands" and stick a funs call in your documentation:<pre><code> usage=$(cat <<USAGE Usage: foo <subcommand> Subcommands: $(funs Subcommands) USAGE ) </code></pre> The sed one-liner above uses the oft-ignored "hold space" which lets you store data that persists between lines. Here's the same sed but expanded with comments:<pre><code> funs(){ sed -n '/^## /h # Store header line in hold space x # Swap out current line with header in hold space. /'"$1"'/{ # Run block if last encountered header matches $1 x # Return to processing current line (instead of header) s/^$\w\+$().*/\1/p # Print function names x # Whether or not this block runs, we want to return to # processing the current line. If the block does not # run, then the hold space contains our current line # with the active line being our header. So we must } # return to that state as whell when the block is run. x # Restore current line from hold space' "$0" }</code></pre>

fomine3almost 5 years ago

I'm particular about: If I run a command and its arguments is wrong, it should output error and help messages to STDERR. But if I run a command with --help argument, it should output help messages to STDOUT.

ahnickalmost 5 years ago

I like the idea of combining the header with the help documentation to reduce the number of areas to maintain in smaller scripts. For larger scripts though, I think I'd still prefer to have a separate function, so that the help documentation doesn't overwhelm the initial viewing of the actual code.I also like to feed a heredoc directly into man, which allows you to achieve nicer formatting for the help documentation. Something like this...<pre><code> man -l - << EOF .\" Manpage for encpass.sh. .\" Email contact@plyint.com to correct errors or typos. .TH man 8 "06 March 2020" "1.0" "encpass.sh man page" .SH NAME encpass.sh \- Use encrypted passwords in shell scripts ... EOF </code></pre> See encpass.sh for a working example of this -> <a href="https://github.com/plyint/encpass.sh/blob/master/encpass.sh" rel="nofollow">https://github.com/plyint/encpass.sh/blob/master/encpass.sh</a>

评论 #23764418 未加载

评论 #23764044 未加载

hansdieter1337almost 5 years ago

Even better: Don’t use bash. I started using Python instead of bash. It’s way better to read and more maintainable. If I need the performance of native-Unix commands, I can still use them using subprocess.

评论 #23767663 未加载

评论 #23776947 未加载

评论 #23765767 未加载

评论 #23765542 未加载

raggialmost 5 years ago

I used this strategy in "fx" which is a development helper frontend for fuchsia builds and tools. I used four # for the "short description" and three for the long description. The reason I used the strategy there is that lot of our scripts delegate arguments to native commands, and so adding help purely to --help wasn't really a good ROI. Implementation: <a href="https://fuchsia.googlesource.com/fuchsia/+/refs/heads/master/scripts/fx#40" rel="nofollow">https://fuchsia.googlesource.com/fuchsia/+/refs/heads/master...</a>

jandresealmost 5 years ago

Hmm:% sed -rn 's/^### ?//;T;p' testfilesed: 1: "s/^### ?//;T;p": invalid command code TLooks like it might need GNU Sed or something. But honestly if I want to read the top of the file less works just as well.

评论 #23763723 未加载

heinrichhartmanalmost 5 years ago

I like to do:<pre><code> help() { cat $0 } </code></pre> "May the source be with you." : )

OliverJonesalmost 5 years ago

Cool. I did this on 7th Edition UNIX in 1977. I forget how. It's interesting that ....* NIX makes people do creative things All that Bell Labs stuff still works the way it always did.* People are still reinventing this particular wheel, and* This embedded help stuff still somehow hasn't made it into the infrastructure along with autocomplete.

jeffromalmost 5 years ago

Something I've wanted to do for a while is build a library to parse and generate use lines / documentation that adheres to the posix useline spec (can't find the link at the moment) while also being able to idempotently (de)serialize and be descriptive enough to define arguments and flags in a way a human could easily understand. iirc the spec seemed probably too vague to just work with all the currently existing man pages, but it would be nice to have a spec all programs can follow that machines can parse on my os.

评论 #23765126 未加载

andsensalmost 5 years ago

My time to shine! I built an argument parser that uses a POSIX compliant help message as the input. It's a parser generator really. It generates minified bash that is inlined in your script, so no dependencies. The work is based off of docopt (and is docopt compliant). Check it out: <a href="https://github.com/andsens/docopt.sh" rel="nofollow">https://github.com/andsens/docopt.sh</a>

flaxtonalmost 5 years ago

Didn't work on macOS (multiple sed errors - switches differ from Linux) but prompted me to write a help function ;-)

评论 #23764870 未加载

评论 #23764892 未加载

owenshen24almost 5 years ago

Unrelated: Is there any connection between the author and the other sam[]zdat who writes about society and other intriguing topics?<a href="https://samzdat.com/" rel="nofollow">https://samzdat.com/</a>

评论 #23765229 未加载

7786655almost 5 years ago

Pretty sure this won't work if the script is called via $PATH

评论 #23764336 未加载

sneakalmost 5 years ago

Why is “./script.sh -h” better than “less script.sh”?

评论 #23766896 未加载

评论 #23766320 未加载

stkaialmost 5 years ago

Handy! Now, can it author the help text as well? ;)

thangalinalmost 5 years ago

There's an endless variation on how shell scripts can present help information. Here's another, consider this array:<pre><code> ARGUMENTS+=( "a,arch,Target operating system architecture (amd64)" "b,build,Suppress building application" "o,os,Target operating system (linux, windows, mac)" "u,update,Java update version number (${ARG_JRE_UPDATE})" "v,version,Full Java version (${ARG_JRE_VERSION})" ) </code></pre> The lines are machine-readable and alignment is computed by the template:<a href="https://github.com/DaveJarvis/scrivenvar/blob/master/build-template#L186" rel="nofollow">https://github.com/DaveJarvis/scrivenvar/blob/master/build-t...</a>When install script[0] help is requested, the following is produced:<pre><code> $ ./installer -h Usage: installer [OPTIONS...] -V, --verbose Log messages while processing -h, --help Show this help message then exit -a, --arch Target operating system architecture (amd64) -b, --build Suppress building application -o, --os Target operating system (linux, windows, mac) -u, --update Java update version number (8) -v, --version Full Java version (14.0.1) </code></pre> Using an array reduces some duplication, though more can be eliminated. Scripts typically have two places where the arguments are referenced: help and switch statements. The switch statements resemble:<a href="https://github.com/DaveJarvis/scrivenvar/blob/master/installer#L191" rel="nofollow">https://github.com/DaveJarvis/scrivenvar/blob/master/install...</a>Usually parsing arguments entails either assigning a variable or (not) performing an action later. Introducing another convention would allow hoisting the switch statement out of the installer script and into the template. Off the cuff, this could resemble:<pre><code> ARGUMENTS+=( "ARG_ARCH,a,arch,Target operating system architecture (amd64)" "do_build=noop,b,build,Suppress building application" "ARG_JRE_OS,o,os,Target operating system (linux, windows, mac)" "ARG_JRE_UPDATE,u,update,Java update version number (${ARG_JRE_UPDATE})" "ARG_JRE_VERSION,v,version,Full Java version (${ARG_JRE_VERSION})" ) </code></pre> The instructions to execute when arguments are parsed are thus associated with the arguments themselves, in a quasi-FP style. This approach, not including the FP convention, is discussed at length in my Typesetting Markdown series[1].[0]: <a href="https://github.com/DaveJarvis/scrivenvar/blob/master/installer" rel="nofollow">https://github.com/DaveJarvis/scrivenvar/blob/master/install...</a>[1]: <a href="https://dave.autonoma.ca/blog/2019/05/22/typesetting-markdown-part-1/" rel="nofollow">https://dave.autonoma.ca/blog/2019/05/22/typesetting-markdow...</a>

oweileralmost 5 years ago

This is not elegant, this is an ugly hack at best.