FASD(1)

💖 fasd(1) — the manual, but make it bestie 💖

okay so this is the page for fasd from the General Commands Manual section, and ngl it's one of the most useful little gremlins you'll ever put in your shell. let's get into it 🫶

---

🌸 NAME 🌸

fasd — quick access to files and directories. that's it, that's the whole name section, she's efficient 💅

---

✨ SYNOPSIS ✨

fasd [options] [query ...]

[f|a|s|d|z] [options] [query ...]

fasd [-A|-D] [paths ...]

---

🎀 OPTIONS 🎀

• -s — list your paths but show the ranks too 👑
• -l — list paths, no ranks, keep it lowkey
• -i — interactive mode, bestie gets a say
• -e <cmd> — set the command to execute on the result file
• -b <name> — use only the <name> backend
• -B <name> — add an additional backend called <name>
• -a — match files and directories (the everything bagel)
• -d — match directories only 📁
• -f — match files only 📄
• -r — match by rank only
• -t — match by recent access only
• -R — reverse the listing order
• -h — show a brief help message
• -[0-9] — select the nth entry

---

👑 DESCRIPTION 👑

Fasd keeps track of the files and directories you access in your shell and gives you quick access to them. you can use fasd to reference files or directories by just a few key identifying characters. and like — you can use fasd to boost your command line productivity by defining your own aliases to launch programs on files or directories. Fasd, by default, provides some basic aliases, including a shell function z that resembles the functionality of z and autojump.

the name fasd comes from the default suggested aliases: f (files), a (files/directories), s (show/search/select), d (directories). cute, right? 🌈

Fasd ranks files and directories by "frecency," that is, by both "frequency" and "recency." the term "frecency" was first coined by Mozilla and used in Firefox. so yes, you're basically running Firefox logic in your terminal, iconic ✨

---

🌟 EXAMPLES 🌟

z bundle
f -e vim nginx conf
f -i rc$
vi `f nginx conf`
cp update.html `d www`
open `sf pdf`

---

🧚 SHELL INITIALIZATION 🧚

to get fasd working in a shell, some initialization code must be run. put the lines below in your POSIX compatible shell rc.

eval "$(fasd --init auto)"

this will setup a command hook that executes on every command and advanced tab completion for zsh and bash. 💫

if you want more control over what gets into your shell environment, you can pass a customized set of arguments to fasd --init.

zsh-hook             # define _fasd_preexec and add it to zsh preexec array
zsh-ccomp            # zsh command mode completion definitions
zsh-ccomp-install    # setup command mode completion for zsh
zsh-wcomp            # zsh word mode completion definitions
zsh-wcomp-install    # setup word mode completion for zsh
bash-hook            # add hook code to bash $PROMPT_COMMAND
bash-ccomp           # bash command mode completion definitions
bash-ccomp-install   # setup command mode completion for bash
posix-alias          # define aliases that applies to all posix shells
posix-hook           # setup $PS1 hook for shells that's posix compatible
tcsh-alias           # define aliases for tcsh
tcsh-hook            # setup tcsh precmd alias

example for a minimal zsh setup (no tab completion):

eval "$(fasd --init posix-alias zsh-hook)"

heads up bestie: this method will slightly increase your shell start-up time, since calling binaries has overhead. 🐌

you can cache fasd init code if you want minimal overhead. example code for bash (to be put into .bashrc):

fasd_cache="$HOME/.fasd-init-bash"
if [ "$(command -v fasd)" -nt "$fasd_cache" -o ! -s "$fasd_cache" ]; then
  fasd --init posix-alias bash-hook bash-ccomp bash-ccomp-install >| "$fasd_cache"
fi
source "$fasd_cache"
unset fasd_cache

optionally, if you can also source fasd if you want fasd to be a shell function instead of an executable.

you can tweak initialization code. for instance, if you want to use c instead of z to do directory jumping, you can use the alias below:

alias c='fasd_cd -d'
# `-d' option present for bash completion
# function fasd_cd is defined in posix-alias

---

🦋 MATCHING 🦋

fasd has three matching modes: default, case-insensitive, and fuzzy. three vibes, one tool 💅

for a given set of queries (the set of command-line arguments passed to fasd), a path is a match if and only if:

1. Queries match the path in order.
2. The last query matches the last segment of the path.

if no match is found, fasd will try the same process ignoring case. if still no match is found, fasd will allow extra characters to be placed between query characters for fuzzy matching. ✨

tips:

• if you want your last query not to match the last segment of the path, append `/' as the last query.
• if you want your last query to match the end of the filename, append `$' to the last query.

---

🌈 COMPATIBILITY 🌈

fasd's basic functionalities are POSIX compliant, meaning that you should be able to use fasd in all POSIX compliant shells. your shell needs to support command substitution in $PS1 in order for fasd to automatically track your commands and files. this feature is not specified by the POSIX standard, but it's nonetheless present in many POSIX compliant shells. in shells without prompt command or prompt command substitution (tcsh for instance), you can add entries manually with fasd -A. you are very welcomed to contribute shell initialization code for not yet supported shells. 🫶

---

⭐ TAB COMPLETION ⭐

fasd offers two completion modes: command mode completion and word mode completion. command mode completion works in bash and zsh. word mode completion only works in zsh.

command mode completion is just like completion for any other commands. it is triggered when you hit tab on a fasd command or its aliases. under this mode your queries can be separated by a space. tip: if you find that the completion result overwrites your queries, type an extra space before you hit tab. 🎀

word mode completion can be triggered on any command. word completion is triggered by any command line argument that starts with , (all), f, (files), or d, (directories), or that ends with ,, (all), ,,f (files), or ,,d (directories). examples:

$ vim ,rc,lo<Tab>
$ vim /etc/rc.local

$ mv index.html d,www<Tab>
$ mv index.html /var/www/

there are also three zle widgets: fasd-complete, fasd-complete-f, fasd-complete-d. you can bind them to keybindings you like:

bindkey '^X^A' fasd-complete    # C-x C-a to do fasd-complete (fils and directories)
bindkey '^X^F' fasd-complete-f  # C-x C-f to do fasd-complete-f (only files)
bindkey '^X^D' fasd-complete-d  # C-x C-d to do fasd-complete-d (only directories)

---

💜 BACKENDS 💜

fasd can take advantage of different sources of recent / frequent files. most desktop environments (like Gtk) and some editors (like Vim) keep a list of accessed files. fasd can use them as additional backends if the data can be converted into fasd's native format. as of now, fasd supports Gtk's recently-used.xbel and Vim's viminfo backends. you can define your own backend by declaring a function by that name in your .fasdrc. you set the default backend with the _FASD_BACKENDS variable in our .fasdrc. 🔥

---

🍓 TWEAKS 🍓

upon every execution, fasd will source /etc/fasdrc and $HOME/.fasdrc if they are present. below are some variables you can set:

• $_FASD_DATA — path to the fasd data file, default "$HOME/.fasd".
• $_FASD_BLACKLIST — list of blacklisted strings. commands matching them will not be processed. default is "--help".
• $_FASD_SHIFT — list of all commands that needs to be shifted, defaults to "sudo busybox".
• $_FASD_IGNORE — list of all commands that will be ignored, defaults to "fasd ls echo".
• $_FASD_TRACK_PWD — fasd defaults to track your "$PWD". set this to 0 to disable this behavior.
• $_FASD_AWK — which awk to use. fasd can detect and use a compatible awk.
• $_FASD_SINK — file to log all STDERR to, defaults to "/dev/null".
• $_FASD_MAX — max total score / weight, defaults to 2000.
• $_FASD_SHELL — which shell to execute. some shells will run faster than others. fasd runs faster with dash and ksh variants.
• $_FASD_BACKENDS — default backends.
• $_FASD_RO — if set to any non-empty string, fasd will not add or delete entries from the database. you can set and export this variable from the command line.
• $_FASD_FUZZY — level of "fuzziness" when doing fuzzy matching. more precisely, the number of characters that can be skipped to generate a match. set to empty or 0 to disable fuzzy matching. default value is 2.
• $_FASD_VIMINFO — path to .viminfo file for the viminfo backend, defaults to "$HOME/.viminfo".
• $_FASD_RECENTLY_USED_XBEL — path to XDG recently-used.xbel file for the recently-used backend, defaults to "$HOME/.local/share/recently-used.xbel".

---

🔥 DEBUGGING 🔥

fasd is hosted on GitHub: https://github.com/clvv/fasd

if fasd does not work as expected, please file a bug report on GitHub describing the unexpected behavior along with your OS version, shell version, awk version, sed version, and a log file. 📝

you can set _FASD_SINK in your .fasdrc to obtain a log.

_FASD_SINK="$HOME/.fasd.log"

---

💀 COPYING 💀

fasd is originally written based on code from z (https://github.com/rupa/z) by rupa deadwyler under the WTFPL license. most if not all of the code has been rewritten. fasd is licensed under the "MIT/X11" license.

---

🌸 AUTHORS 🌸

Wei Dai <x@wei23.net>.

---

and that's the whole page bestie!! this was the fasd user manual, dated Jul 16, 2012, living in section FASD(1) — go forth and jump directories like the main character you are 💖✨🦋👑