ZF(1)

💅 zf(1) — the fuzzy finder bestie 💅

okay so this is the manual page for zf, a general commands manual entry, and honestly? she's that girl. let's get into it 🫶

---

✨ NAME ✨

zf — a commandline fuzzy finder that prioritizes matches on filenames 🎀

---

🌸 SYNOPSIS 🌸

zf [options]

that's it. that's the whole vibe check. 💅

---

🦋 DESCRIPTION 🦋

zf is a simple, general-purpose fuzzy finder, and her whole personality trait is that she prioritizes matches on filenames. iconic behavior, no notes. ✨

she reads a list of newline separated strings on stdin and pops open an interactive interface. hit enter and the selected line goes out on stdout, boom, done. you can also type text to filter the list of strings, which is lowkey the whole point. 🍓

you can mark multiple lines as selected with tab and shift-tab (yes, both, she's flexible). when multiple lines are selected and you press enter, only the marked lines get written to stdout. periodt.

each whitespace-separated term in the query string gets used separately to narrow down the search results. for example, searching for "init config" will select all results that match both "init" and "config". so like, both things have to be true, it's giving AND logic. 🧠

heads up bestie: the query is restricted to a maximum of 16 whitespace-separated tokens. sixteen. that's the limit. don't push her. 😭

matching is case insensitive unless there's an uppercase letter found in the query — then she starts caring about case, main character energy. 👑

---

💖 OPTIONS 💖

• -d, --delimiter — set the delimiter used to split candidates (default \n)
• -0 — shorthand for -d'\0' to split on null bytes 🫶
• -f, --filter — skip interactive use and filter using the given query (no UI, just vibes and output)
• --height — the height of the interface in rows (default 10)
• -k, --keep-order — don't sort by rank and preserve order of lines read on stdin. this makes zf remove any lines that don't match, but the order of lines will not change. lowkey respectful of your input ngl 💀
• -l, --lines — alias of --height. deprecated and will be removed in version 1.0.0. she's on her way out, say your goodbyes 🙈
• -p, --plain — treat input as plaintext and disable filepath matching features. useful when the input lines are not file paths. not everything is a path, bestie 💅
• --preview — executes a command substituting {} with the current selected line and displays the output in a side column. very demure, very side-column. ✨
• --preview-width — sets the preview column width (default 60%)
• -v, --version — show version information and exit
• -h, --help — display help and exit

---

🌈 ENV VARIABLES 🌈

• ZF_PROMPT — override the default > prompt by assigning a string to this variable. for example export ZF_PROMPT="$ ". make it yours, bestie 🎀
• ZF_HIGHLIGHT — set the color used to highlight matches. valid colors are: black, red, green, yellow, blue, magenta, cyan, white bright_black, bright_red, bright_green, bright_yellow, bright_blue, bright_magenta, bright_cyan, and bright_white. the default color is cyan. the bright ones are literally so extra, obsessed 💜
• ZF_VI_MODE — when this variable is present and not empty ctrl+k moves up a line. when disabled ctrl+k deletes from the cursor to the end of line. two completely different personalities depending on one env var, iykyk 👀
• NO_COLOR — disables colors. see https://no-color.org. some of y'all hate fun and that's valid 🌸

---

⭐ COMMANDS ⭐

• enter — write the selected line or all marked lines to stdout and exit
• escape, ctrl-c — exit zf without selecting anything (the dramatic exit, no commitment 💀)
• up, ctrl-p, ctrl-k — select the next line up
• down ctrl-n, ctrl-j — select the next line down
• tab — mark the current line as selected and select the next line
• shift-tab — mark the current line as selected and select the previous line
• left, ctrl-b — move the cursor left
• right, ctrl-f — move the cursor right
• ctrl-a — move the cursor to the beginning of the line
• ctrl-e — move the cursor to the end of the line
• backspace, ctrl-h — delete the character before the cursor
• delete, ctrl-d — delete the character under the cursor
• ctrl-w — delete the word before the cursor
• ctrl-u — delete from the cursor to the beginning of the line

---

🔥 EXAMPLES 🔥

• find -type f | zf — fuzzy find on the file tree in the current directory
• vim $(find -type f | zf) — fuzzy find on the file tree and open the selected file in vim
• git switch $(git branch | cut -c 3- | zf) — switch to selected git branch
• find -type f | zf --preview 'cat {}' — fuzzy find files and show a preview of the contents using cat

---

👑 EXIT STATUS 👑

• 0 — success 🎉
• 1 — no candidates given on stdin or aborted the interactive interface with esc or ctrl-c (the "never mind" exit 😭)
• 2 — error 💀

---

💜 AUTHOR 💜

written by Nathan Craddock ✨

---

okay that's the whole page, bestie — and like any good icon she's got a version and a date: zf 0.10.3, dated 2024-10-28. go forth and fuzzy find, you're gonna slay 🦋💅🎀