314 lines
10 KiB
Groff
314 lines
10 KiB
Groff
.TH "FASD" "1" "Jul 16, 2012" "fasd user manual" ""
|
|
.SH NAME
|
|
.PP
|
|
fasd \- quick access to files and directories
|
|
.SH SYNOPSIS
|
|
.PP
|
|
fasd [options] [query ...]
|
|
.PP
|
|
[f|a|s|d|z] [options] [query ...]
|
|
.PP
|
|
fasd [\-A|\-D] [paths ...]
|
|
.SH OPTIONS
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\-s\ \ \ \ \ \ \ \ \ list\ paths\ with\ ranks
|
|
\-l\ \ \ \ \ \ \ \ \ list\ paths\ without\ ranks
|
|
\-i\ \ \ \ \ \ \ \ \ interactive\ mode
|
|
\-e\ <cmd>\ \ \ set\ command\ to\ execute\ on\ the\ result\ file
|
|
\-b\ <name>\ \ only\ use\ <name>\ backend
|
|
\-B\ <name>\ \ add\ additional\ backend\ <name>
|
|
\-a\ \ \ \ \ \ \ \ \ match\ files\ and\ directories
|
|
\-d\ \ \ \ \ \ \ \ \ match\ directories\ only
|
|
\-f\ \ \ \ \ \ \ \ \ match\ files\ only
|
|
\-r\ \ \ \ \ \ \ \ \ match\ by\ rank\ only
|
|
\-t\ \ \ \ \ \ \ \ \ match\ by\ recent\ access\ only
|
|
\-R\ \ \ \ \ \ \ \ \ reverse\ listing\ order
|
|
\-h\ \ \ \ \ \ \ \ \ show\ a\ brief\ help\ message
|
|
\-[0\-9]\ \ \ \ \ select\ the\ nth\ entry
|
|
\f[]
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.PP
|
|
Fasd keeps track of 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.
|
|
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."
|
|
.PP
|
|
The name "fasd" comes from the default suggested aliases
|
|
\f[C]f\f[](files), \f[C]a\f[](files/directories),
|
|
\f[C]s\f[](show/search/select), \f[C]d\f[](directories).
|
|
.PP
|
|
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.
|
|
.SH EXAMPLES
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
z\ bundle
|
|
f\ \-e\ vim\ nginx\ conf
|
|
f\ \-i\ rc$
|
|
vi\ `f\ nginx\ conf`
|
|
cp\ update.html\ `d\ www`
|
|
open\ `sf\ pdf`
|
|
\f[]
|
|
.fi
|
|
.SH SHELL INITIALIZATION
|
|
.PP
|
|
To get fasd working in a shell, some initialization code must be run.
|
|
Put lines below in your POSIX compatible shell rc.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
eval\ "$(fasd\ \-\-init\ auto)"
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
This will setup a command hook that executes on every command and
|
|
advanced tab completion for zsh and bash.
|
|
.PP
|
|
If you want more control over what gets into your shell environment, you
|
|
can pass customized set of arguments to \f[C]fasd\ \-\-init\f[].
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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\[aq]s\ posix\ compatible
|
|
tcsh\-alias\ \ \ \ \ \ \ \ \ \ \ #\ define\ aliases\ for\ tcsh
|
|
tcsh\-hook\ \ \ \ \ \ \ \ \ \ \ \ #\ setup\ tcsh\ precmd\ alias
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Example for a minimal zsh setup (no tab completion):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
eval\ "$(fasd\ \-\-init\ posix\-alias\ zsh\-hook)"
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Note that 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):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Optionally, if you can also source \f[C]fasd\f[] if you want
|
|
\f[C]fasd\f[] to be a shell function instead of an executable.
|
|
.PP
|
|
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:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
alias\ c=\[aq]fasd_cd\ \-d\[aq]
|
|
#\ `\-d\[aq]\ option\ present\ for\ bash\ completion
|
|
#\ function\ fasd_cd\ is\ defined\ in\ posix\-alias
|
|
\f[]
|
|
.fi
|
|
.SH MATCHING
|
|
.PP
|
|
Fasd has three matching modes: default, case\-insensitive, and fuzzy.
|
|
.PP
|
|
For a given set of queries (the set of command\-line arguments passed to
|
|
fasd), a path is a match if and only if:
|
|
.IP "1." 3
|
|
Queries match the path in order.
|
|
.IP "2." 3
|
|
The last query matches the last segment of the path.
|
|
.PP
|
|
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.
|
|
.PP
|
|
Tips:
|
|
.IP \[bu] 2
|
|
If you want your last query not to match the last segment of the path,
|
|
append `/\[aq] as the last query.
|
|
.IP \[bu] 2
|
|
If you want your last query to match the end of the filename, append
|
|
`$\[aq] to the last query.
|
|
.SH COMPATIBILITY
|
|
.PP
|
|
Fasd\[aq]s basic functionalities are POSIX compliant, meaning that you
|
|
should be able to use fasd in all POSIX compliant shells.
|
|
Your shell need 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\[aq]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.
|
|
.SH TAB COMPLETION
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
Word mode completion can be triggered on \f[I]any\f[] 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:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ vim\ ,rc,lo<Tab>
|
|
$\ vim\ /etc/rc.local
|
|
|
|
$\ mv\ index.html\ d,www<Tab>
|
|
$\ mv\ index.html\ /var/www/
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
There are also three zle widgets: "fasd\-complete", "fasd\-complete\-f",
|
|
"fasd\-complete\-d".
|
|
You can bind them to keybindings you like:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
bindkey\ \[aq]^X^A\[aq]\ fasd\-complete\ \ \ \ #\ C\-x\ C\-a\ to\ do\ fasd\-complete\ (files\ and\ directories)
|
|
bindkey\ \[aq]^X^F\[aq]\ fasd\-complete\-f\ \ #\ C\-x\ C\-f\ to\ do\ fasd\-complete\-f\ (only\ files)
|
|
bindkey\ \[aq]^X^D\[aq]\ fasd\-complete\-d\ \ #\ C\-x\ C\-d\ to\ do\ fasd\-complete\-d\ (only\ directories)
|
|
\f[]
|
|
.fi
|
|
.SH BACKENDS
|
|
.PP
|
|
Fasd can take advantage of different sources of recent / frequent files.
|
|
Most desktop environments (such as OS X and Gtk) and some editors (such
|
|
as Vim) keep a list of accessed files.
|
|
Fasd can use them as additional backends if the data can be converted
|
|
into fasd\[aq]s native format.
|
|
Below is a list of available backends.
|
|
.IP \[bu] 2
|
|
spotlight: OSX spotlight, provides entries that are changed today or
|
|
opened within the past month
|
|
.IP \[bu] 2
|
|
recently\-used: GTK\[aq]s recently\-used file (Usually available on
|
|
Linux)
|
|
.IP \[bu] 2
|
|
current: Provides everything in $PWD (whereever you are executing
|
|
\f[C]fasd\f[])
|
|
.IP \[bu] 2
|
|
viminfo: Vim\[aq]s editing history, useful if you want to define an
|
|
alias just for editing things in vim
|
|
.PP
|
|
You can define your own backend by declaring a function by that name in
|
|
your \f[C]\&.fasdrc\f[].
|
|
You can set default backend with \f[C]_FASD_BACKENDS\f[] variable in our
|
|
\f[C]\&.fasdrc\f[].
|
|
.SH TWEAKS
|
|
.PP
|
|
Upon every execution, fasd will source "/etc/fasdrc" and "$HOME/.fasdrc"
|
|
if they are present.
|
|
Below are some variables you can set:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$_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
|
|
database.\ You\ can\ set\ and\ export\ this\ variable\ from\ 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\ viminfo\ backend,\ defaults\ to\ "$HOME/.viminfo"
|
|
|
|
$_FASD_RECENTLY_USED_XBEL
|
|
Path\ to\ XDG\ recently\-used.xbel\ file\ for\ recently\-used\ backend,\ defaults\ to
|
|
"$HOME/.local/share/recently\-used.xbel"
|
|
\f[]
|
|
.fi
|
|
.SH DEBUGGING
|
|
.PP
|
|
Fasd is hosted on GitHub: https://github.com/clvv/fasd
|
|
.PP
|
|
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.
|
|
.PP
|
|
You can set \f[C]_FASD_SINK\f[] in your \f[C]\&.fasdrc\f[] to obtain a
|
|
log.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
_FASD_SINK="$HOME/.fasd.log"
|
|
\f[]
|
|
.fi
|
|
.SH COPYING
|
|
.PP
|
|
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.
|
|
.SH AUTHORS
|
|
Wei Dai <x@wei23.net>.
|