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 $SAVEHISTExpected (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 histExpected:
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 $HISTFILEExpected (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_SPACEis 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 viaread -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*' 1Expected (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; doneExpected:
"^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
⌥Cand⌃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
atuincall withoutATUIN_CONFIG_DIRcreates~/.config/atuinand~/.local/share/atuin, even a harmlessatuin 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 zshExpected (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/projektWhat 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 -lExpected:
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 0Expected:
✔ 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 inmysql -p…. Get used to the leading space and maintainhistory_filterin atuin. Check from time to time withrg -i 'token|passw|secret' $HISTFILE. - atuin sync via
api.atuin.shis 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,
!$,fcandhistory | grepstill work there. SHARE_HISTORYis 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.