Workflows general

Workflows: general

Everyday workflows provided by this project. For git-specific workflows see Workflows: git. For remote access see Workflows: remote. For system maintenance see Workflows: maintenance. For the full alias and function reference see Shell Environment.

Terminal setup

The primary environment is Ghostty with tmux. The backup is Kitty with tmux.

Both emulators are configured by this project (~/.config/ghostty/, ~/.config/kitty/). tmux configuration lives in ~/.config/tmux/ with plugin management via TPM. See Application Notes for tmux plugin installation and Kitty-specific setup.

CLI editing

The shell uses fzf for fuzzy finding everywhere:

• Ctrl+R — search command history (with preview; pet snippets are accessible via Alt+s when pet is installed).
• Ctrl+T — insert a file path from the current tree.
• Alt+C — cd into a subdirectory.

Standard readline keys work as expected: Left/Right, Home/End, Backspace/Delete.

Clipboard: Ctrl+Shift+C to copy, Ctrl+Shift+V to paste. Inside tmux, selecting text copies it automatically.

Navigating the file tree

Navigation uses zoxide (z), which learns from your cd history and jumps to the best match:

Command	What it does
z foo	Jump to the most-used directory matching foo.
..	Go up one level (z ..).
...	Go up two levels. ...., .4, .5 go further.
up N	Go up exactly N levels.
zl foo	Jump to a directory and list its contents.
zp foo	Jump like z foo, keeping where you were on the directory stack (pushd).
zdirs	Pick a directory from the stack with fzf and go there; Ctrl-R rotates, Ctrl-D or Backspace drops, Esc closes.
zpop	Go back to the previous directory on the stack (popd).

Working with files and directories

mkdir creates intermediate directories by default (-pv).

mkz (alias mkcd) creates a directory and jumps into it in one step:

mkz new-project

The default editor is Micro (mic), set via EDITOR and VISUAL. Any program that honors those variables — git commit, sudoedit, crontab -e — opens Micro automatically.

Copy, move, and delete have safety nets: cp and mv are interactive and verbose; rm prompts before bulk deletes and protects /.

For large transfers, rsync-based aliases show a progress bar:

Alias	Description
rcp	rsync copy with aggregate progress bar.
rmv	rsync move with aggregate progress bar (removes source).
rup	Recursive update (skip newer files at destination).
rsy	Recursive sync (update + delete files absent from source).

Searching

Code search

rg (ripgrep) is the primary tool for searching file contents. It respects .gitignore, skips binary files, and is fast on large trees:

rg "TODO"                    # search all files
rg "TODO" src/               # search within src/
rg -t js "import"            # search only JavaScript files
rg -i "error" --glob "*.log" # case-insensitive, only .log files

For interactive filtering of ripgrep results, pipe through fzf:

rg "pattern" | fzf

gre is a simpler recursive grep that excludes common junk directories (node_modules, .git, venv, dist, build). Useful when you want basic grep syntax without learning ripgrep flags:

gre "pattern" .
gre -l "TODO" src/     # list files only

where combines find + grep with file-type filtering via glob patterns:

where "TODO"                    # search all files in current dir
where "import" "src/*.js"       # search only .js files under src/
where "class" "*.py"            # search Python files

Finding files

fd is the primary tool for finding files by name. Like ripgrep, it respects .gitignore and is fast:

fd "config"              # find files matching "config"
fd -e json               # find all .json files
fd -H ".env"             # include hidden files

Searching upward

Three commands search the current directory and each parent up to / (or $HOME with -h). Useful for finding config files (.env, package.json, Makefile) from anywhere in a project tree:

Command	Backend	Example
upfind	find	upfind -name "Makefile"
upfd	fd	upfd Makefile
upsearch	fd (glob + hidden)	upsearch ".env*"

upsearch "package.json"        # find nearest package.json above
upfd -h Makefile               # stop at $HOME instead of /

Git-aware fuzzy search (fzf-git)

Inside a git repository, Ctrl+G followed by a second key opens an fzf picker for git objects:

Keys	What it searches
Ctrl+G F	Modified/tracked files
Ctrl+G B	Branches
Ctrl+G T	Tags
Ctrl+G H	Commit hashes (log)
Ctrl+G R	Remotes
Ctrl+G S	Stashes

Selected items are inserted at the cursor. See fzf-git.sh for the full list.

Which search tool when?

Situation	Tool
Search file contents in a project	rg (fastest, respects .gitignore)
Interactive content search	rg … | fzf
Recursive grep without learning new syntax	gre
Search specific file types by glob	where "pattern" "*.ext"
Find a file by name	fd
Find a config file somewhere above you	upsearch or upfind
Browse git objects interactively	Ctrl+G (fzf-git)

File managers

Three terminal file managers are available:

Command	Tool	Best for
mc	Midnight Commander	Two-pane file operations, bulk rename, FTP/SFTP
yazi	Yazi	Fast navigation with image preview, vim-like keys
br	Broot	Fuzzy tree search, quick navigation in deep trees

Getting help

Three tools for quick command references:

Command	What it is
help (aliased to tldr)	Community-maintained cheat sheets with common usage examples.
cheat	Personal and community cheat sheets, editable.
pet	Snippet manager — save, search, and replay commands. Ctrl+x Ctrl+r to search.