summaryrefslogtreecommitdiff
path: root/doc/bash-style.cli
blob: d22cc231275ebcee43038751ab2a5697535db0ab (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
// file      : doc/bash-style.cli
// copyright : Copyright (c) 2014-2018 Code Synthesis Ltd
// license   : MIT; see accompanying LICENSE file

"\title=Bash Style Guide"

// NOTES
//
// - Maximum <pre> line is 70 characters.
//

"\h1|Table of Contents|"
"\$TOC$"

"
\h1#intro|Introduction|

Bash works best for simple tasks. Needing arrays, arithmetic, and so on, is
usually a good indication that the task at hand is too complex for Bash.

Most of the below rules can be broken if there is a good reason for it.
Besides making things consistent, rules free you from having to stop and think
every time you encounter a particular situation. But if it feels that the
prescribed way is clearly wrong, then it probably makes sense to break it.
You just need to be clear on why you are doing it.

See also \l{https://google.github.io/styleguide/shell.xml Google's Bash Style
Guide} as well as \l{https://github.com/progrium/bashstyle Let's do Bash
right!}; we agree with quite a few (but not all) items in there. In particular,
the former provides a lot more rationale compared to this guide.

\h1#style|Style|

Don't use any extensions for your scripts. That is, call it just \c{foo}
rather than \c{foo.sh} or \c{foo.bash}. Use lower-case letters and dash
to separate words, for example \c{foo-bar}.

Indentation is two spaces (not tabs). Maximum line length is 79 characters
(excluding newline). Use blank lines between logical blocks to improve
readability.

Variable and function names should use lower-case letters with underscores
separating words.

For \c{if}/\c{while} and \c{for}/\c{do} the corresponding \c{then} or \c{do}
is written on the same line after a semicolon, for example:

\
if [ ... ]; then
fi

for x in ...; do
done
\

For \c{if} use \c{[ ]} for basic tests and \c{[[ ]]} only if the previous form
is not sufficient. Use \c{test} for filesystem tests (presence of files,
etc). Do use \c{elif}.

\h1#struct|Structure|

The overall structure of the script should be as follows:

\
#! /usr/bin/env bash

# <SUMMARY>
#
# [<FUNCTIONALITY-DESCRIPTION>]
#
# [<OPTIONS-DESCRIPTION>]
#
usage=\"usage: $0 <OPTIONS>\"

owd=\"$(pwd)\"
trap \"{ cd '$owd'; exit 1; }\" ERR
set -o errtrace # Trap in functions.

function info () { echo \"$*\" 1>&2; }
function error () { info \"$*\"; exit 1; }

[<OPTIONS-ARGUMENTS-DEFAULTS>]

[<OPTIONS-ARGUMENTS-PARSING>]

[<OPTIONS-ARGUMENTS-VALIDATION>]

<FUNCTIONALITY>
\

\h#struct-summary|SUMMARY|

One-two sentences describing what the script does.

\h#struct-func-desc|FUNCTIONALITY-DESCRIPTION|

More detailed functionality description for more complex scripts.

\h#struct-opt-desc|OPTIONS-DESCRIPTION|

Description of command line options. For example:

\
# -q
#   Run quiet.
#
# -t <dir>
#   Specify the alternative toolchain installation directory.
\

\h#struct-opt|OPTIONS|

Command line options summary. For example:

\
usage=\"usage: $0 [-q] [-t <dir>] <file>\"
\

\h#struct-opt-arg-default|OPTIONS-ARGUMENTS-DEFAULTS|

Set defaults to variables that will contain option/argument values. For
example:

\
quiet=\"n\"
tools=/usr/local
file=
\

\h#struct-opt-arg-parse|OPTIONS-ARGUMENTS-PARSING|

Parse the command line options/arguments. For example:

\
while [ \"$#\" -gt 0 ]; do
  case \"$1\" in
    -q)
      quiet=\"y\"
      shift
      ;;
    -t)
      shift
      tools=\"${1%/}\"
      shift
      ;;
    *)
      if [ -n \"$file\" ]; then
        error \"$usage\"
      fi

      file=\"$1\"
      shift
      ;;
  esac
done
\

If the value you are expecting from the command line is a directory path,
the always strip the trailing slash (as shown above for the \c{-t} option).

\h#struct-opt-arg-valid|OPTIONS-ARGUMENTS-VALIDATION|

Validate option/argument values. For example:

\
if [ -z \"$file\" ]; then
  error \"$usage\"
fi

if [ ! -d \"$file\" ]; then
  fail \"'$file' does not exist or is not a directory\"
fi
\

\h#struct-func|FUNCTIONALITY|

Implement script logic. For diagnostics use the \c{info()} and \c{error()}
functions defined above (so that it goes to stderr, not stdout). If using
functions, then define them just before use.

\h1#quote|Quoting|

We quote every variable expansion, no exceptions. For example:

\
if [ -n \"$foo\" ]; then
  ...
fi
\

This also applies to command substitution (which we always write as
\c{$(foo arg)} rather than \c{`foo arg`}), for example:

\
list=\"$(cat foo)\"
\

Note that a command substitution creates a new quoting context, for example:

\
list=\"$(basename \"$1\")\"
\

We also quote values that are \i{strings} as opposed to options/file names,
paths, or integers. If setting a variable that will contain one of these
unquoted values, try to give it a name that reflects its type (e.g.,
\c{foo_file} rather than \c{foo_name}). Prefer single quotes for \c{sed}
scripts, for example:

\
proto=\"https\"
quiet=\"y\"
verbosity=1
dir=/etc
out=/dev/null
file=manifest
seds='s%^./%%'
\

Note that quoting will inhibit globbing so you may end up with expansions
along these lines:

\
rm -f \"$dir/$name\".*
\

\N|One exception to this quoting rule is arithmetic expansion (\c{$((\ ))}):
Bash treats it as if it was double-quoted and, as a result, any inner quoting
is treated literally. For example:

\
z=$(($x + $y))           # Ok.
z=$((\"$x\" + \"$y\"))       # Error.
z=$(($x + $(echo \"$y\"))) # Ok.
\

|


If you have multiple values (e.g., program arguments) that may contain spaces,
don't try to handle them with quoting and use arrays instead. Here is a
typical example of a space-aware argument handling:

\
files=()

while [ \"$#\" -gt 0 ]; do
  case \"$1\" in

    ...

    *)
      shift
      files=(\"${files[@]}\" \"$1\")
      shift
      ;;
  esac
done

rm -f \"${files[@]}\"
\

In the same vein, never write:

\
cmd $*
\

Instead always write:

\
cmd \"$@\"
\

Also understand the difference between \c{@} and \c{*} expansion:

\
files=('one' '2 two' 'three')
echo \"files: ${files[@]}\"  # $1='files: one', $2='2 two', $3='three'
echo \"files: ${files[*]}\"  # $1='files: one 2 two three'
\

\h1#trap|Trap|

Our scripts use the error trap to automatically terminate the script in case
any command fails. If you need to check the exit status of a command, use
\c{if}, for example:

\
if grep \"foo\" /tmp/bar; then
  info \"found\"
fi

if ! grep \"foo\" /tmp/bar; then
  info \"not found\"
fi
\

Note that the \c{if}-condition can be combined with capturing the output, for
example:

\
if v=\"$(...)\"; then
  ...
fi
\

If you need to ignore the exit status, you can use \c{|| true}, for example:

\
foo || true
\


\h1#bool|Boolean|

For boolean values use empty for false and \c{true} for true. This way you
can have terse and natural looking conditions, for example:

\
first=true
while ...; do

  if [ ! \"$first\" ]; then
     ...
  fi

  if [ \"$first\" ]; then
     first=
  fi

done
\

\h1#function|Functions|

If a function takes arguments, provide a brief usage after the function
header, for example:

\
function dist() # <pkg> <dir>
{
  ...
}
\

For non-trivial/obvious functions also provide a short description of its
functionality/purpose, for example:

\
# Prepare a distribution of the specified packages and place it into the
# specified directory.
#
function dist() # <pkg> <dir>
{
  ...
}
\

Inside functions use local variables, for example:

\
function dist()
{
  local x=\"foo\"
}
\

If the evaluation of the value may fail (e.g., it contains a program
substitution), then place the assignment on a separate line since \c{local}
will cause the error to be ignore. For example:

\
function dist()
{
  local b
  b=\"$(basename \"$2\")\"
}
\

For more information on returning data from functions, see
\l{https://mywiki.wooledge.org/BashFAQ/084 BashFAQ#084}.

For more information on writing reusable functions, see
\l{https://stackoverflow.com/questions/11369522/bash-utility-script-library
Bash Utility Script Library}.
"