path: root/docs/projects/bash-workshop.md

# bash workshop

2023-03-09

On two consecutive Sunday evenings (2023-02-26 and 2023-03-05) I hosted
the bash workshop on behalf of <abbr title="tech department under JI
student union">TechJI</abbr>.

![I am standing in front of a projector screen in an
auditorium](img/bash-workshop/workshop.jpg)

▲ Me delivering the talky part of the workshop

## Topics

Despite its name, much of this workshop is not about bash alone, but other
tools as well. Here is a brief list:

### Part 1

- Intro
    * Brief history
    * Unix philosophy
- Files & File Tree
    * `cat, cp, mv, rm`
    * `cd, pwd, ls, mkdir`
    * Paths, `.`, `..`, `*`
- CLI
    * Options and arguments
    * Reading man pages
    * Keyboard shortcuts
- Pipes
    * stdin, stdout
    * `>` and `>>`
    * Pipes
    * `grep`

### Part 2

- Regex (ERE)
    * Patterns
    * `grep -E`
    * `sed -E 's///'`
    * Capturing groups
- Scripting
    * Variables
    * `if`
    * `for`

## Goal

I've been on Linux for 5 years. It would be a shame if I kept all that
bash knowledge to myself. I believe bash is something that every
computer-related major student should know, for the following reasons:

1. Efficiency. Bash has saved hours if not days of my time and will save
   yours as well.

2. Portability. Literally every server you may ssh into will have a shell
   of some sort, and having a hint of how it works will surely help.

Therefore, the aim of bash workshop is

1. Learn commands/scripts/tricks to boost efficiency

2. Make the most out of GNU coreutils and a few common tools you'd find
   anywhere

## Materials used

- Slides (2x, ~50 pages each totalling 1.5k lines of LaTeX)
- Cheatsheet (A4 sheet handed out on site)
- Tarball (Follow-along examples and DIY materials)

Participants were asked to download a zip file containing all three.

## Design

Work began in October 2022. I scraped together all the topics I feel
confident sharing with others, and then kicked out what I felt wasn't
common enough. For example `tr` and `cut`.

In November 2022 I approached Prof. Manuel Charlemagne with an early draft
to ask if he had any advice. The draft was not yet split in half; it was
a 71-page giant mess. His advice was to

- Pack less in one workshop
- Create fun activities to engage participants
- Remove that distracting navbar on the bottom

![A bar of buttons](img/bash-workshop/navbar.png)

▲ Navbar in the default LaTeX beamer theme

I decided that the workshop should follow a practicality-first approach,
so I filled the slides with examples that's like, "yeah you'll have to
figure this out sooner or later, so I'll show you how right now".

![Slide screenshot](img/bash-workshop/environment_variables.png)

▲ Slide in section 5, "Bash Scripting"

<details markdown="1">
<summary>Transcript</summary>
Environment variables

Let's say you're downloading something from a completely legal website,
and you want the traffic to go through your completely legal local proxy
for completely legal reasons.

```
# set environment variable for local proxy
$ export HTTPS_PROXY=http://localhost:8080/
# download the thing
$ curl -O https://legal.website/legal-thing
```
</details>

I also designed DIY sessions at the end of each section where I ask every
participant to run some commands, design a regex, write a script, etc.

![Slide screenshot](img/bash-workshop/cli_challenge.png)

▲ Challenge session at the end of section 2, "CLI"

<details markdown="1">
<summary>Transcript</summary>
Challenge

- Read the man page for head
- Experiment with files in `02-cli/`
- Find a command to generate the following:

```
==> p0.txt <==
MANIFESTO OF THE COMMUNIST PARTY.
==> p1.txt <==
I. BOURGEOIS AND PROLETARIANS.
```

Solution

```
$ head -n1 -v p0.txt p1.txt
```
</details>

By the way, the navbar can be removed with

```
\setbeamertemplate{navigation symbols}{}
```

### Cheatsheet

The cheatsheet is a compilation of commands, regexes and syntax I covered.

![Part of cheatsheet](img/bash-workshop/cheatsheet.png)

▲ I spent 6 RMB on 30 copies. 13 were handed out on site.

### Easter eggs

![Slide screenshot](img/bash-workshop/bash_history.png)

▲ On top of practicality I tried my best to sprinkle some humor.

<details markdown="1">
<summary>Transcript</summary>
A brief history of bash

- Born: 1989
- Probably played Pokémon on the Game Boy
- Is an umbrella term for zsh, fish, …
- Runs on Unix-like environments
</details>

![Slide screenshot](img/bash-workshop/ultimate_challenge.png)

▲ The final DIY challenge at the very end

<details markdown="1">
<summary>Transcript</summary>
The Ultimate Challenge

Each line in `05-scripting/obf.txt` begins with an 8-digit number.
Print every line with its number greater than any of the lines above.

```
IFS=$'\n'
max=0
for line in $(cat obf.txt); do
    num=$(echo $line | grep -oE '^[0-9]{8}')
    if [[ $num -gt $max ]]; then
        echo $line
        max=$num
    fi
done
```
</details>

Now, with so much said and done, be prepared for the best trolling in
TechJI's history.

<details markdown="1">
<summary>You probably won't be surprised…</summary>
![ASCII art of Rick Astley](img/bash-workshop/rickroll.png)
</details>

## Advertising

We needed to advertise our event to get people to come. I wrote the first
draft on 2023-02-16, which begins with the place, time, topics and
prerequisites, followed by the actual marketing.

I ask readers to imagine themselves as an intern who received a message
from their boss:

"And here's some simpler work for you… ssh into the server, backup the
logs in `/var/log`, and grep the error codes generated within one minute
past each hour, then deduplicate them and…"

The intern panics, for they never touched bash other than the bare minimum
to pass <abbr title="CS intro course">VG151</abbr>. Panic turns into
regret — that they failed to show up on our workshop.

And thus the manipulation is done; reader is brainwashed to participate.

(No, of course they aren't.)

![Bash workshop: A Quarter Century of Unix](img/bash-workshop/wechat.png)

▲ Header banner of WeChat article

Two more revisions finalized the article on 2023-02-22. My venue
reservation was approved the next day, but not yet confirmed via email, so
I delayed posting.

By Saturday, 2023-02-25, I realized it was Too Fucking Late™ and urgently
sent the article anyway. However I was told we can't because WeChat limits
our account to only one batch of articles each day, and it's already out
there.

(TechJI used to have its own account, but after some reformation all
departments share one account, JISU.)

This means we have to advertise for a Sunday event — on Sunday. The
article dropped at 10 o'clock.

Lesson learned: never pretend to play safe when you hear the clock
ticking.

## How it went

### Attendance

\# of participants who showed up in person are 10 and 4, respectively, for
the two parts.

4 was a bit low but given the abundance of competing events that night
(there was an art festival and a guitar concert which, had there been no
bash workshop, I would be vibing to). However, this meant a high
attention-per-person.

### Timing

Part 1 lasted around 1.5 hr; part 2 lasted 2.5. Part of the 2.5 was
troubleshooting one by one.

In retrospect I should have kicked out `sed` and capturing groups. This
will eliminate one DIY session which I admit is a bit overwhelming for
those who heard the word "regex" for the first time.

### Unexpected technical problems

- Accessing WSL filesystem might be tricky in Windows
- One person trapped themselves in vim
- bash refuses to execute scripts with `\r\n` linebreaks
- On MacBooks, the default bash is FreeBSD flavor and parses `{01..05}` as
  `{1..5}`

## Reflection

Here is a list of things I will fix if I were to do it again.

I will test the scripts on macOS;

I will prepare the promotional article sooner so it gets published at
least three days before the event, not nine hours;

I will recap the conventions from part 1 so they don't confuse
participants in part 2;

![edited xkcd](img/bash-workshop/average_familiarity.png)

▲ [Original: "Average Familiarity"](https://xkcd.com/2501/)

<details markdown="1">
<summary>Transcript</summary>
Two stick figures have a conversation.

"The command line is second nature to us Linux users, so it's easy to
forget that the average person probably only knows how to use coreutils
and one or two regexes."

"And tar cvf of course."

"Of course."

Caption: Even when they're trying to compensate for it, experts in
anything wildly overestimate the average person's familiarity with their
field.
</details>

I will clarify where participants should `cd` into before they run
commands;

I will emphasize the difference between:

- `var` and `$var`
- `echo $str` and `cat file`
- `echo $str | COMMAND` and `COMMAND $str`

## Conclusion

If workshops were children this would be my firstborn. To build a workshop
from scratch is gratifying, especially when the topic is an extract of my
five years of experience. I would like to thank Prof. Manuel Charlemagne;
the feedback was very useful.

I learned how to weigh things — to tell things that matter from those that
don't — and how to make it worth the time for both friends and strangers.

However, I need to rework my strategy toward event preparation. I should
have pushed forward more aggressively. Few problems are worse than running
out of time. There was no need to play safe.

```
$ ~ exit
```