Your first shell script

Before you read. Every morning you check the same three things: whether the backup ran, how full the disk is, and whether the service came back up. Three commands, typed the same way, for a month.

The commands are correct. You already know them. Nothing about this needs learning.

So what is actually different about putting those three lines in a file?

Almost nothing, and that is the point worth starting from. A shell script is a file containing commands you would have typed anyway, run in order. There is no new language to learn before you can write a useful one, you already know the language, because it is the shell.

What this lesson is really about is the small number of things that are different: how the system knows the file is meant to be run, how the file gets told what to work on, and two habits that decide whether it still works next month on somebody else’s machine.

Some words you will need

script

A text file of commands, run top to bottom by an interpreter.

shebang

The #! on the first line, naming which interpreter runs the file.

interpreter

The program that reads the script and does what it says. Usually bash.

argument

Something given to the script on the command line. Available as $1, $2, and so on.

exit status

A number from 0 to 255 the script leaves behind. Zero means success.

word splitting

The shell breaking an unquoted value apart at spaces. The cause of most script bugs.

What breaks without this

The knowledge stays in your head. A procedure only you can perform is a procedure that does not happen while you are on holiday, and one nobody can review for correctness.

It works differently every time. Three commands typed by hand are three opportunities to mistype, skip one, or run them in the wrong order at 3am.

You cannot schedule it. Everything in the scheduling lesson (cron, timers, CI) needs something to run, and that something is a file.

And the one that catches people later: a script that works on your machine and fails on the server, for reasons that have nothing to do with what it does.

The smallest script that does anything

A file, three lines, no ceremony:

#!/bin/bash
name="$1"
echo "Good morning, $name"
echo "It is $(date +%A)"

$(date +%A) is command substitution: run date +%A, and put its output here. The rest is a variable and two echos.

Save it as greet.sh and run it.

# Debian 13 (trixie), x86_64
$ cat greet.sh; echo "--- try to run it ---"; ./greet.sh Ryan; echo "rc=$?"
#!/bin/bash
name="$1"
echo "Good morning, $name"
echo "It is $(date +%A)"
--- try to run it ---
/bin/sh: 1: ./greet.sh: Permission denied
rc=126

Permission denied, and this is everybody’s first script error. Creating a file does not make it runnable. A new file is rw-r--r-- (readable and writable by you, readable by everyone, executable by nobody) and running it requires the execute bit from lesson 07.

rc=126 is worth recognising. It is not a generic failure: 126 means “found it, could not execute it”, which is a permissions or format problem. Compare it to 127, which means “did not find it at all”. Those two numbers distinguish a typo in the filename from a missing execute bit without any further investigation.

One chmod fixes it:

# Debian 13 (trixie), x86_64
$ ls -l greet.sh; chmod +x greet.sh; ls -l greet.sh; echo "--- now ---"; ./greet.sh Ryan; echo "rc=$?"
-rw-r--r--. 1 root root 74 Aug  8 22:15 greet.sh
-rwxr-xr-x. 1 root root 74 Aug  8 22:15 greet.sh
--- now ---
Good morning, Ryan
It is Saturday
rc=0

chmod +x without a target sets it for everyone, subject to your umask, which is what you want for a script in /usr/local/bin. chmod u+x sets it for you only, which is right for something in your home directory.

And ./greet.sh needs the ./. The shell searches $PATH for bare command names, and . is not on $PATH, deliberately, since a directory containing a file called ls could otherwise hijack the real one. Naming the path explicitly says “this file, here”.

The shebang decides which language you are writing

The first two characters of the file are #!, and the kernel reads them before anything else happens. They name the program that will interpret the rest.

This matters more than it looks, because /bin/sh and /bin/bash are not the same program on most systems. On Debian and Ubuntu, /bin/sh is dash, a smaller, faster, strictly POSIX shell with no arrays, no [[ ]], and no for ((;;)).

# Debian 13 (trixie), x86_64
$ cat wrongshebang.sh; echo "--- run it ---"; ./wrongshebang.sh; echo "rc=$?"
#!/bin/sh
names=(alpha beta)
echo "${names[0]}"
--- run it ---
./wrongshebang.sh: 2: Syntax error: "(" unexpected
rc=2

Syntax error: "(" unexpected, from a script whose syntax is perfectly correct, for a different shell. The shebang did not describe the file; it chose the interpreter, and dash does not have arrays.

This is the single most common portability failure in shell scripting, and it has a memorable shape: the script works when you run bash script.sh and fails when you run ./script.sh, because only the second form consults the shebang.

Use #!/bin/bash when you use bash features, and mean it. Writing #!/bin/sh because it looks more portable, and then using bash syntax, gives you the worst of both: it appears to work on Red Hat, where /bin/sh is bash, and breaks on Debian.

A file with no shebang at all still runs, which confuses the picture. The shell that invoked it runs it as a child of itself, so it works from an interactive bash prompt and behaves unpredictably when something else (cron, a systemd unit, a CI runner) executes it with a different shell. Always write one.

Taking arguments

A script that only ever does one thing is a note to yourself. A script that takes an argument is a tool.

The positional parameters arrive as numbered variables, plus three that describe the set:

# Debian 13 (trixie), x86_64
$ cat args.sh; echo "--- run it with three arguments ---"; ./args.sh alpha beta gamma
#!/bin/bash
echo "script name: $0"
echo "first arg:   $1"
echo "how many:    $#"
echo "all of them: $@"
--- run it with three arguments ---
script name: ./args.sh
first arg:   alpha
how many:    3
all of them: alpha beta gamma

$0 is not an argument, which is why $# is 3 and not 4. It holds whatever path was used to run the script, so a script can behave differently depending on the name it was called by. That is how gzip, gunzip, and zcat are one binary.

"$@" versus "$*" is a real distinction and worth learning once. Quoted, "$@" expands to each argument as a separate word, preserving spaces inside them. "$*" joins everything into a single word. Passing arguments along to another command is always "$@".

script_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &> /dev/null && pwd)
source "$script_dir/config.sh"

script_dir=$(dirname -- "$(readlink -f -- "${BASH_SOURCE[0]}")")

Handling the case where there is no argument

The most common bug in a first script is assuming it was given what it needs. The fix is three lines at the top:

#!/bin/bash
src="$1"
dest="/var/backups"
if [ -z "$src" ]; then
    echo "usage: backup.sh SOURCE" >&2
    exit 2
fi
echo "would copy $src to $dest"

[ -z "$src" ] is true when the variable is empty. >&2 sends the message to standard error, from lesson 19, so it does not pollute output somebody is piping. And exit 2 sets the status deliberately.

# Debian 13 (trixie), x86_64
$ ./backup.sh; echo "rc=$?"; echo "--- and with an argument ---"; ./backup.sh /etc; echo "rc=$?"
usage: backup.sh SOURCE
rc=2
--- and with an argument ---
would back up /etc
rc=0

Zero for success and non-zero for failure, which is the convention everything else relies on. &&, ||, if, set -e, cron’s failure mail, a systemd unit’s Restart=on-failure, and every CI system read that number.

The conventional values are worth using:

A script that always exits 0 is a script nothing can react to, and it is the reason a broken nightly job can run silently for months.

Quoting is not punctuation

This is the habit that separates a script that works from one that works on everyone’s data. The rule is short: put double quotes around every variable expansion, unless you have a specific reason not to.

Here is why, on the most ordinary input imaginable, a filename with a space in it.

# Debian 13 (trixie), x86_64
$ cat quoting.sh; echo "--- run it on a filename with a space ---"; ./quoting.sh "my report.txt"
#!/bin/bash
file="$1"
echo "without quotes, the shell splits it:"
printf '  [%s]\n' $file
echo "with quotes, it stays one thing:"
printf '  [%s]\n' "$file"
--- run it on a filename with a space ---
without quotes, the shell splits it:
  [my]
  [report.txt]
with quotes, it stays one thing:
  [my report.txt]

Two arguments instead of one. The shell performed word splitting on the unquoted value, and printf was handed my and report.txt as separate things.

Now imagine that value went to rm instead of printf. rm $file deletes two files, neither of them the one you meant, and neither of them exists so you get two errors and no clue. The same expansion inside cp, mv, or a for loop produces the same class of damage.

The variable holds the right value the whole time. Nothing is corrupted; the shell is doing exactly what it is documented to do with an unquoted expansion. The quotes are how you say “this is one thing”.

When not to quote is a much shorter list: when you actively want splitting, which is rare and should carry a comment.

#!/bin/bash
set -euo pipefail
IFS=$'\n\t'

# Debian 13 (trixie), x86_64
$ bash -c "echo start; nosuchcommand; echo carried on anyway"; echo "rc=$?"; echo "--- with set -e ---"; bash -c "set -e; echo start; nosuchcommand; echo never printed"; echo "rc=$?"
start
bash: line 1: nosuchcommand: command not found
carried on anyway
rc=0

Asking the person running it

read takes a line from standard input into a variable. It is how a script asks a question:

# Debian 13 (trixie), x86_64
$ cat ask.sh; echo "--- feed it two answers ---"; printf "/srv/data\ny\n" | ./ask.sh
#!/bin/bash
read -r -p "Which directory? " target
read -r -p "Are you sure? [y/N] " reply
if [ "$reply" = "y" ]; then
    echo "would back up $target"
else
    echo "cancelled"
fi
--- feed it two answers ---
would back up /srv/data

The prompts do not appear in the output, because read -p writes them to standard error rather than standard output, which is correct, and means piping a script’s output does not capture its questions.

-r should be on every read you ever write. Without it, backslashes in the input are treated as escapes, so a user pasting a Windows path gets it mangled. There is no case where the default is what you want.

The bigger point is about when to ask at all. A script that asks questions cannot be scheduled, cannot run in CI, and cannot be used non-interactively. Prefer arguments, and use read only for genuinely interactive tools, or gate it:

if [ -t 0 ]; then
    read -r -p "Are you sure? [y/N] " reply
else
    reply=y
fi

[ -t 0 ] is true when standard input is a terminal, so the script asks a person and assumes yes when piped.

Across distributions

Scripting is one of the most portable things in this track. What differs is what /bin/sh points at, and where scripts belong.

That second row is the whole reason to be careful. A script written and tested on RHEL with #!/bin/sh and bash syntax appears correct, and fails the first time it runs on Ubuntu. Testing with dash script.sh catches it before deployment.

Prove it

# Does it parse at all, without running anything
bash -n script.sh

# What is it actually doing, line by line
bash -x script.sh /some/arg

# What will somebody else's shell make of it
dash script.sh

# What does a linter think
shellcheck script.sh

# And the one that matters
./script.sh; echo "exit status $?"

bash -n is the pre-flight check and costs nothing, it parses without executing, so a syntax error in a rarely-taken branch is found before that branch is taken at 3am.

bash -x prints each line as it runs, with variables expanded, which answers “what did it actually do” faster than adding echo statements. set -x inside the script turns it on partway through, and set +x turns it off.

What trips people up

1. Permission denied on a script you just wrote

Creating a file does not make it executable. chmod +x script.sh.

rc=126 specifically means “found it, could not run it”, which distinguishes this from 127, “not found at all”.

2. ./ is required and looks like a typo

script.sh searches $PATH, which does not include the current directory. ./script.sh names the file where it is. Put scripts in /usr/local/bin and the ./ stops being necessary.

3. Bash syntax under #!/bin/sh

Works on RHEL, fails on Debian, because /bin/sh is dash there. Syntax error: "(" unexpected on a line that is valid bash is this every time.

Write #!/bin/bash when you use bash features.

4. bad interpreter: No such file or directory

The missing file is the interpreter, not the script. Nearly always a carriage return from a Windows editor: the kernel is looking for /bin/bash\r.

file script.sh says “CRLF line terminators”. dos2unix fixes it.

5. Unquoted variables

rm $file on my report.txt deletes two things, neither of them right. rm "$file" does what you meant.

The value was never wrong; the shell split it because you did not say it was one thing.

6. Exiting 0 no matter what

Nothing downstream can react. Cron will not mail you, systemd will not restart it, CI will pass. Use exit 1 for failure and exit 2 for misuse.

Work it through

You are asked to turn the three morning checks into a script. The first version looks like this, and somebody else will run it:

#!/bin/sh
cd $1
tar -czf backup.tar.gz *
echo done

Reason it out before reading on. There are four problems and they are not equally serious.

cd $1 is two problems in one line. It is unquoted, so a directory with a space in it becomes two arguments and cd fails. And the failure is not checked, the script carries on to the next line, where tar -czf backup.tar.gz * now runs in whatever directory the script started in. That is the serious one: it does not fail, it succeeds against the wrong data.

cd "$1" || exit 1

No argument check. With no argument, cd "" fails, and with set -e absent the same wrong-directory problem follows. Three lines at the top fix it.

#!/bin/sh with no bash features is actually fine here, but it is a decision nobody made. If the next person adds an array, it breaks on Debian and works in their testing on RHEL.

And echo done with no exit status means the caller cannot tell a successful backup from a failed one. tar sets a status; the script discards it by ending with an echo that always succeeds.

The repaired version:

#!/bin/bash
set -euo pipefail

src="${1:-}"
if [ -z "$src" ]; then
    echo "usage: $0 SOURCE" >&2
    exit 2
fi

cd "$src" || exit 1
tar -czf /var/backups/backup.tar.gz .

Note what disappeared. There is no echo done, because the exit status says it, and with set -e, reaching the end at all means everything succeeded. A script that prints “done” whether or not it worked is worse than one that prints nothing.

The point worth extracting: the dangerous failures in a script are the ones where something succeeds at the wrong thing. A command that errors is visible. A cd that quietly failed, followed by a command that quietly worked in the wrong directory, produces a backup file full of the wrong data and a successful exit status, and nobody looks at it until they need to restore.

Try it

Optional, and everything here is safe.

1. Write greet.sh with the three lines from the top of this lesson. Run it before chmod +x and note the exit status.
2. chmod +x it and run it again with your name.
3. Delete the shebang and run it. Then run dash ./greet.sh and compare.
4. Add echo "you gave me $# arguments" and run it with none, then with three.
5. Make a file called my report.txt. Write a script that takes a filename and runs ls -l $1 unquoted. Run it against that file and read the error.
6. Add the quotes. Run it again.
7. Put set -euo pipefail at the top of any script and introduce a typo in a command name. Compare the exit status with and without it.
8. Run bash -x on any of them and watch the expansion.

Verification step. You have it when you can explain, without running anything, why ./script.sh and bash script.sh can behave differently on the same file.

Check yourself

cmd || { echo "cmd failed" >&2; exit 1; }

References

• bash(1) - Linux man-pages project. Accessed 2026-08-08.
• execve(2) - Linux man-pages project. Accessed 2026-08-08.
• chmod(1) - Linux man-pages project. Accessed 2026-08-08.
• exit(3) - Linux man-pages project. Accessed 2026-08-08.
• dash(1) - Debian manpages. Accessed 2026-08-08.
• Shell Command Language - The Open Group. Accessed 2026-08-08.

Every block above with a distribution and architecture header was captured by running the command on a Debian 13 (trixie) container. Blocks without one are illustrative.