Consider changing the way we introduce `mkdir -p`

[nbraunsc]

How could the content be improved?

During my teaching demo, I found that when we introduce the mkdir -p concept it was confusing (and the instructor also agreed). I also saw there was another issue raised about this section in April.

When we say:

Note that mkdir is not limited to creating single directories one at a time. The -p option allows mkdir to create a directory with nested subdirectories in a single operation:

$ mkdir -p ../project/data ../project/results

It is pretty confusing for the following reasons:

1. We are combining two different concepts that may be overlooked. We are using the -p command (without explaining what it actually stands for) and we are creating two directories at the same time. The main idea about how -p allows you to create directories in a different location might be overlooked.
2. We never cd into the /project directory first to show what the current folders/files are, therefore it is not super straight forward that it actually created them.
3. We also never end up using these directories.

A few suggestions could be something like we first cd ../projects and then ls to show the contents. Then we cd ../ and pwd to show that we are in /Users/nelle/Desktop/shell-lesson-data/exercise-data/. Then introduce the path idea (without the ../) so it would be mkdir -p /projects/data. Followed by ls -FR project/.

Then if you wanted to show that you can make multiple directories at the same time (although, I don't think this is super important), then you could run mkdir -p projects/results projects/conclusions.

I personally almost never use the -p command but if we do want to teach it, then I think some reorganizing about this concept would be beneficial to the learners. Thanks!

Which part of the content does your suggestion apply to?

https://github.com/swcarpentry/shell-novice/blob/main/episodes/03-create.md

[lharms23]

Suggesting improved sequence for introducing mkdir -p

I also recently taught this episode during an instructor training and also found the current mkdir -p example confusing for learners, especially because it combines several ideas at once. I would like to propose a more incremental sequence that separates these concepts and makes it easier to see what -p does.

1. Start from a known location and show the baseline

$ pwd
/Users/nelle/Desktop/shell-lesson-data
$ mkdir project
$ cd project
$ ls # empty

2. Introduce -p with a single nested path:
   Now show the basic idea of -p without also creating multiple directories:

$ mkdir -p data
$ ls
data/

Explain: "mkdir creates one directory at a time. The -p option (think 'parents') lets us create parent directories as needed, and it does nothing if they already exist."

Then show a nested directory:

$ mkdir -p results/figures
$ ls
data/  results/
$ ls results
figures/

Here the effect of -p is visible: it created results/ and results/figures/ in one go.

3. Show that -p is safe if directories already exist:

$ mkdir -p results/figures
$ mkdir -p data

Explain: “Running the same command again does not give an error and does not delete anything. -p quietly succeeds if the directory is already there.”

4. (Optional) Only then show creating multiple directories in one command:

$ mkdir -p results/tables results/models
$ ls -R
.:
data/  results/

./data:

./results:
figures/  models/  tables/

You can emphasize that this is a convenience feature, not something learners must memorize.

I think this sequence improves the lesson because:

• It separates the core idea of -p (creating parent/nested directories safely) from the additional idea of creating multiple directories in one command.
• It always starts from a known working directory and uses pwd/ls before and after, so learners can clearly see what changed at each step.
• It introduces -p with simple paths first (no ../ yet), and only later adds slightly more complex examples if time allows.
• It matches how many people actually use mkdir -p in practice: to create safe nested directory structures that may or may not already exist.

[omsai]

I personally almost never use the -p command

I commonly use it to create a directory without erroring if a directory already exists.

$ cd
$ mkdir Downloads/
mkdir: Downloads/: File exists
$ echo $?
1
$ mkdir -p Downloads/
$ echo $?
0

Because of how the bash shell defaults to continuing even if a command returns an error, I first make any error stop execution with set +x. After enabling set +x, if I didn't use mkdir -p, my bash script would stop even though I don't care that the directory exists. I use -p in that context more often than creating nested directories. Hopefully that helps you see the value of -p.

We are combining two different concepts that may be overlooked.

Working with relative directories was exhaustively covered in the previous lesson; this is a chance to reinforce what you just taught. Your job as the instructor is to point out that detail.

We never cd into the /project directory first to show what the current folders/files are, therefore it is not super straight forward that it actually created them.

You just showed that mkdir creates directories by showing what the directory looked like before creating the thesis/ directory.

I hesitate with suggestions calling for adding many more commands to the shell-novice lesson because we really want to minimize how much typing we are subjecting the students to.