i didnt care about how i wrote my bash scripts, coz i know theyd ultimately be used just by myself. but for the past few day, i’ve been working on this project, mk-blog which uses some bash scripts, there are chances that others might look at them. besides in work they’re asking me maintain a server. so why not learn the standards. but i couldn’t find anything good online (i’m gonna blame my search engine lol). so…
i’d appreciate redirections to (official or community) bash coding standards
ShellCheck is a static analysis tool for bash/sh scripts - try it on your scripts. The README also shows some examples of what (not) to do.
The link to your project gives me a 404 btw, is it a private repository?
You don’t need a plugin, just use the bash LSP server with any editor that support LSP servers. It supports explainshell, shellcheck and shfmt.
“Just”, lol. I’m sure yours is a much more comprehensive and powerful solution, but it definitely looks more complex than just installing a plugin on your IDE!
Don’t know about everyone else, but here are some of mine:
- Stick to posix compliance shell code, wherever possible
- Please wrap your variables with { }. Just please.
- Global variables being exported in all caps
- Local variables in lower case
- $() instead of ` `
- Comment anything complicated, comment what section, comment usage
- Include usage output if options are not recognized
- Use case instead of if / elif, where possible
- 80 characters or less per line, where possible
- HERE docs in designated section, marked by comment blocks
- Comment your functions immediately above it’s definition
- Add comment “#End of function Xyz” at line immediately below a function, with replacing Xyz with name of that function
- 2 space indentation
- Multi-line strings: First line open with quote and first line of string, followed by a backslash , subsequent lines properly indented and backslashed. Last line, properly indented and close quoted.
- Break up multiple piping of commands with |\ and a new line where it makes sense to look nice, assisting readability
- Echo what the script is doing once in a while if the user will be waiting for a while
- Please don’t do shar archives, or byte located binary extractions, make a script and a separate tarball - Helps a ton if we have to change it, like say… swapping out a bundled java runtime built for x86_64 with one for aarch64
- If the script will run for a very long time, check for tmux or screen and also the TMOUT variable… Give a warning to the user their connection might time out before the script is done if they don’t unset TMOUT, and try using tmux or screen to allow the script to continue in the background, even if you do get disconnected
- Make use of logger
- I try to organize a script this way: 1. Shebang, 2. Initial variable definitions, 3. Functions, 4. runtime execution code, which might be best outside of a function, and calling functions. 5. Clean-up (remove pid and lock files, tmp files, etc etc.)
- utilize awk if you need to process (=more complex than just grepping) large amounts of text.
-
- make your awk code conform to at least busybox awk for compability
I once did a sh script that needed (because I wanted a challenge?) to be compatible with vanilla Android shell too. So I needed to test it with regular bash, busybox and mksh+toybox. That was ‘fun’.
I’ve had some initial plans to spllit the code out from that project and develop a “shell” library that would ease building shell scripts that are compatible with different systems… But I bet someone else has already done that.
A yes, the fear of opensourcing.
Trust me, proprietary code is often total garbage because nobody looks at it.
There is no single Bash standard to follow, only a few guidelines. One way you can check for some basic errors and formatting would be using an editor with support for Bash (in best case with a builtin LSP). At the end, you have to find your style and coding standards or adapt what others do if you want work with them or edit their files.
- Otherwise there is a well known tool for checking Bash files: https://www.shellcheck.net/ You can use it online and as a downloaded program on your local machine. After using shellcheck for a bit I got used to some of its conventions and recommendations, such as always wrapping variables like in
${variable}and some other things. - Google has a coding style guide, but not everyone likes it: https://google.github.io/styleguide/shellguide.html
- Related is the Bash Reference Manual from GNU: https://www.gnu.org/software/bash/manual/bash.html Off course this is not a guide on how to style or program, but it helps in understanding how GNU does things.
BTW the mk-blog link is 404 for me.
If your bash script gets longer than 200 lines (including argument handling), use Python. I have to support bash APPLICATIONS at work and it’s a fucking nightmare to maintain.
I would then assume those scripts weren’t written properly to begin with.
But yes, shell scripts should be used (normally) to automate some simple tasks (file copying, backups…) or as an wrapper to exec some other program. I’ve written several shell scripts to automate things on my personal machines.
However shell script can be complex program while at the same time being (somewhat) easy to maintain:
- functions, use functions, alot
-
- comment every function and describe what it expects in stdin or as an arguments
-
- also comment what it outputs or sets
This way at least I don’t break my scripts, when I need to modify a function or some way extend my scripts. Keeping the UNIX philosophy inside shell scripts: let one function do one thing well.
And of course: YMMV. People have wastly different coding standards when it comes to personal little(?) projects.
I had several tests at the beginning of the script. These tests define the “low-level” functions based the capability of the shell. To test new features I “simply” ran all the necessary commands on the test environments (bash, busybox, toybox+mksh).
The script would error out if some necessary capability was missing from the host system. It also had a feature to switch shell if it found a better one (preferring busybox and its internal tools).
Yeah… It was tedious process. It was one of those “I’ll write a simple script. So simple that it’ll work on almost every posixy shell.”… rest is history.
