Skip to content
Hands-on IT IT Drills

Day 4: History mastery

Goal: Every command you’ve ever typed is back in two seconds – filtered by text, directory or exit code. · Duration: approx. 75 min · Prerequisite: Day 3

Briefing

  • The history is your personal runbook. Senior engineers rarely type long commands twice, they search for them.
  • Default on the Mac: 2000 entries in memory, 1000 in the file, without timestamps. That’s too little.
  • Three search levels: ↑ with a prefix, ⌃R (built-in or with fzf), atuin (SQLite database with directory, exit code and duration).
  • Secrets don’t belong in the history. A space in front of the command keeps it out.
 Typing ──► zsh history (~/term-lab/zsh/.zsh_history)  ◄── ↑, ⌃R (fzf)
        └─► atuin DB (~/term-lab/data/atuin/history.db) ◄── ⌥R
            + directory, exit code, duration, session

Drill 1: Setting up the history properly

echo $HISTFILE $HISTSIZE $SAVEHIST

Expected (before the drill):

/Users/du/term-lab/zsh/.zsh_history 2000 1000

These values are set by /etc/zshrc. Now your own file:

cat > ~/term-lab/config/zsh/history.zsh <<'EOF'
# ~/term-lab/config/zsh/history.zsh – history (Day 4)
HISTFILE=$ZDOTDIR/.zsh_history
HISTSIZE=100000
SAVEHIST=100000
setopt EXTENDED_HISTORY        # store timestamp and duration
setopt SHARE_HISTORY           # write immediately, share between shells
setopt HIST_IGNORE_SPACE       # " command" doesn't land in the history
setopt HIST_IGNORE_ALL_DUPS    # remove older duplicates
setopt HIST_REDUCE_BLANKS      # strip superfluous spaces
setopt HIST_VERIFY             # show !! first, then run with ⏎

# ↑ / ↓ search for what's already typed
autoload -Uz up-line-or-beginning-search down-line-or-beginning-search
zle -N up-line-or-beginning-search
zle -N down-line-or-beginning-search
for k in '^[[A' '^[OA'; do bindkey -M emacs $k up-line-or-beginning-search; done
for k in '^[[B' '^[OB'; do bindkey -M emacs $k down-line-or-beginning-search; done
EOF
exec ~/term-lab/lab
echo $HISTSIZE $SAVEHIST
setopt | grep hist

Expected:

100000 100000
extendedhistory
histignorealldups
histignorespace
histreduceblanks
histverify
sharehistory
Option Why
SHARE_HISTORY a command from tab 1 is available immediately via ↑ in tab 2, in tmux panes too
HIST_IGNORE_ALL_DUPS git status is in there only once, namely the most recent
HIST_VERIFY sudo !! first shows the finished command, a second ⏎ runs it
EXTENDED_HISTORY every line with start time and duration

Save your progress? Sign up for free

Drill 2: What’s in the file?

Type a few commands in the project; the fourth one starts with a space:

cd ~/term-lab/projekt
git status --short
wc -l logs/app.log
 export API_TOKEN=sk-lab-geheim-1234
grep   ERROR   logs/app.log | wc -l
tail -4 $HISTFILE

Expected (your timestamps will differ):

: 1791615295:0;git status --short
: 1791615296:0;wc -l logs/app.log
: 1791615297:0;grep ERROR logs/app.log | wc -l
: 1791615299:0;tail -4 $HISTFILE

Format: : <start time in Unix seconds>:<duration>;<command>. The export with the lab token is missing, and the double spaces in the grep are gone.

Security: HIST_IGNORE_SPACE is a safety net, not a vault. The command stays retrievable via ↑ until the next command and appears in the process list. Read real tokens from a file, a password manager or via read -s.

Save your progress? Sign up for free

Drill 3: ↑ with a prefix

Type just git and press ↑:

[lab] projekt % git status --short▮

Without a prefix, ↑ pages through everything as usual. With a prefix, only through commands that start that way. Press ↑ again to go further back. That alone replaces many ⌃R searches.

Save your progress? Sign up for free

Drill 4: Built-in search and fc

First the built-in tools, because they exist on every server. Press ⌃R and type ERR:

grep ERROR logs/app.log | wc -l
bck-i-search: ERR_

Pressing ⌃R again jumps to the next older match. ⏎ runs it, ⌃E or → takes the line for editing, ⌃G cancels.

For lists there’s fc. history is the same as fc -l:

history -i -3
fc -l -m 'git*' 1

Expected (shortened, your numbers and times will differ):

    5  2026-10-10 08:55  wc -l logs/app.log
    6  2026-10-10 08:55  grep ERROR logs/app.log | wc -l
    7  2026-10-10 08:56  tail -4 $HISTFILE
    1  git status --short

-i shows date and time, -m filters by glob, the 1 means “from entry 1”. Two more tricks:

Command Effect
r repeat the last command
r wc repeat the last command that starts with wc
fc open the last command in $EDITOR, run it after :wq
fc -l -20 the last 20 commands

Save your progress? Sign up for free

Drill 5: fzf for ⌃R

fzf turns ⌃R into a fuzzy search with a list. You type word fragments in any order, fzf finds the line.

cat > ~/term-lab/config/zsh/fzf.zsh <<'EOF'
# ~/term-lab/config/zsh/fzf.zsh – fzf basics (Day 4, extended on Day 7)
# ⌃R history, ⌃T files, ⌥C change directory
source <(fzf --zsh)
export FZF_CTRL_R_OPTS="--height 40% --layout reverse --info inline"
EOF
exec ~/term-lab/lab
for k in '^R' '^T' '^[c'; do bindkey $k; done

Expected:

"^R" fzf-history-widget
"^T" fzf-file-widget
"^[c" fzf-cd-widget

Now ⌃R and type log wc. It looks roughly like this (display may differ depending on version):

> log wc
  3/9 ──────────────────────────────────────
> grep ERROR logs/app.log | wc -l
  wc -l logs/app.log

⏎ puts the line into the prompt; it only runs with another ⏎. In the fzf window:

Key Effect
⌃J / ⌃K or ↓ / ↑ move the selection
⌃R toggle sorting: by relevance or by time
⇥ mark several lines
'wort exact match instead of fuzzy
^git / log$ start / end of the line
!kubectl exclude lines with kubectl
⌃C / Esc cancel

Warning: fzf rebinds ⌥C and ⌃T. On Day 3 those were “capitalize word” and “transpose characters”. If you need them, bind them to another key. You’ll go deeper into ⌃T and ⌥C on Day 7.

Save your progress? Sign up for free

Drill 6: atuin – history as a database

atuin stores every command in SQLite, together with directory, exit code, duration, host and session. Sync between machines is optional and end-to-end encrypted. We leave it off.

Warning: Every atuin call without ATUIN_CONFIG_DIR creates ~/.config/atuin and ~/.local/share/atuin, even a harmless atuin default-config. In this book, call atuin only in the lab shell.

First the lab configuration, then the shell hookup:

mkdir -p ~/term-lab/config/atuin
cat > ~/term-lab/config/atuin/config.toml <<EOF
# Lab configuration for atuin – everything stays under ~/term-lab
data_dir = "$HOME/term-lab/data/atuin"
auto_sync = false
update_check = false
enter_accept = false
filter_mode = "global"
style = "compact"
inline_height = 20
history_filter = ["^ ", "sk-lab-"]
EOF
cat > ~/term-lab/config/zsh/atuin.zsh <<'EOF'
# ~/term-lab/config/zsh/atuin.zsh – atuin on ⌥R (Day 4), ⌃R stays with fzf
export ATUIN_CONFIG_DIR=$LAB/config/atuin
eval "$(atuin init zsh --disable-ctrl-r --disable-up-arrow)"
bindkey -M emacs '^[r' atuin-search
EOF
exec ~/term-lab/lab
atuin info | grep 'db path'

Expected:

client db path: /Users/du/term-lab/data/atuin/history.db
meta db path: /Users/du/term-lab/data/atuin/meta.db

Why ⌥R and not ⌃R? That way you have both tools side by side and decide later. --disable-up-arrow leaves ↑ to the prefix search from Drill 3. enter_accept = false makes ⏎ only put the command into the prompt instead of running it right away. history_filter holds regular expressions for commands atuin never stores.

Import the existing lab history:

HISTFILE=$HISTFILE atuin import zsh

Expected (shortened):

Importing history from zsh
Import complete!

The HISTFILE=$HISTFILE in front matters: zsh doesn’t export the variable. Without it, atuin reads ~/.zsh_history, i.e. your real history.

Now ⌥R. atuin opens a list with duration and time, something like this (display may differ depending on version):

  5ms  0s ago  grep -c ERROR logs/app.log
  4ms  1m ago  wc -l logs/app.log
       ...
[ GLOBAL ] >

In the window, ⌃R switches the filter: GLOBAL, HOST, SESSION, DIRECTORY. ⇥ takes the line for editing, Esc cancels.

Save your progress? Sign up for free

Drill 7: Searching by directory and exit code

Create a few entries with success and failure in two directories:

cd ~/term-lab/projekt
grep -c ERROR logs/app.log
cat gibtsnicht.txt
cd internal/cart
head -5 cart.go
ls
 export LAB_TOKEN=lab-wert-ohne-bedeutung
echo sk-lab-master-1234
cd ~/term-lab/projekt

What went wrong?

atuin search --exclude-exit 0 --cwd . --format "{exit}  {command}"

Expected:

1  cat gibtsnicht.txt

What did I do in internal/cart? --cwd needs an absolute path:

atuin search --cwd $PWD/internal/cart --format "{duration}  {command}"

Expected (your times will differ):

7ms  head -5 cart.go
2ms  ls

And the secrets?

atuin search LAB_TOKEN | wc -l
atuin search sk-lab | wc -l

Expected:

       0
       0

The first is missing because of the space, the second because of history_filter. By the way, entries imported from the zsh history have exit code -1 and no directory. Only atuin itself knows that data.

Question Command
What ran here in this folder? atuin search --cwd .
What failed? atuin search --exclude-exit 0
What only ran successfully? atuin search --exit 0 kubectl
What ran since yesterday? atuin search --after yesterday
What was slow? atuin search --format "{duration} {command}"
How often do I type what? atuin stats

Save your progress? Sign up for free

Shortcut table

Key Effect Mnemonic
↑ / ↓ history, filtered by prefix up = earlier
⌃R search the history (fzf) Reverse search
⌃R in fzf sorting relevance / time Reorder
⌥R atuin search R with extras
⌃R in atuin filter: global, host, session, folder Range
⌃G cancel search (built-in) Go away
⌥. last word of the previous command dot = the last one
␣befehl not into the history space = quiet
r repeat the last command repeat
fc last command in the editor fix command

Checkpoint

LAB=${LAB:-~/term-lab}
ok() { local m=$1; shift; "$@" >/dev/null 2>&1 && echo "✔ $m" || echo "✘ $m"; }
lab() { env ZDOTDIR="$LAB/zsh" zsh -i -c "$1" 2>/dev/null; }
ok "100000 Einträge"       test "$(lab 'echo $SAVEHIST')" -ge 100000
ok "Leerzeichen-Schutz"    lab '[[ -o histignorespace ]]'
ok "geteilte History"      lab '[[ -o sharehistory ]]'
ok "↑ mit Präfix"          lab '[[ $(bindkey "^[[A") == *beginning-search ]]'
ok "⌃R = fzf"              lab '[[ $(bindkey "^R") == *fzf-history-widget ]]'
ok "⌥R = atuin"            lab '[[ $(bindkey "^[r") == *atuin-search ]]'
ok "atuin-DB im Lab"       lab 'atuin info | grep -q "db path: $LAB/data/atuin"'
ok "kein Lab-Token in DB"  test "$(lab 'atuin search sk-lab | wc -l')" -eq 0

Expected:

✔ 100000 Einträge
✔ Leerzeichen-Schutz
✔ geteilte History
✔ ↑ mit Präfix
✔ ⌃R = fzf
✔ ⌥R = atuin
✔ atuin-DB im Lab
✔ kein Lab-Token in DB

And the practical test: open a second split with the lab shell using ⌘D. Type echo aus-dem-linken-split on the left, ↑ on the right. Thanks to SHARE_HISTORY, the command appears immediately.

Challenge

Show all failed commands from the last seven days that you ran in the project folder. Newest first, with time and exit code.

Hint: atuin search --help knows filters for exit code, directory and time, as well as --reverse.

Solution

cd ~/term-lab/projekt
atuin search --exclude-exit 0 --cwd $PWD --after "7 days ago" --reverse \
  --format "{time}  {exit}  {command}"

Expected (your times will differ):

2026-10-10 08:57:23  1  cat gibtsnicht.txt

--after understands natural expressions like yesterday or "2 hours ago". If you need this more often, turn it into a fails function on Day 5.

Save your progress? Sign up for free

Enterprise Note

  • The history is a security risk: tokens in curl -H "Authorization: …", passwords in mysql -p…. Get used to the leading space and maintain history_filter in atuin. Check from time to time with rg -i 'token|passw|secret' $HISTFILE.
  • atuin sync via api.atuin.sh is encrypted, but still leaves the company network. Ask data protection and security before turning it on. Alternative: your own atuin server in the company network, or no sync.
  • On jump hosts and in containers there’s neither fzf nor atuin. ⌃R, !$, fc and history | grep still work there.
  • SHARE_HISTORY is handy, but mixes commands from parallel sessions. If you work against prod in one pane, use the history search there especially deliberately (Day 14).
  • Shared admin accounts with a shared history are an audit nightmare. Personal accounts plus central logging (e.g. auditd or session recording on the bastion host) are the standard.