Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/andrewferrier/fzf-z

Plugin for zsh to integrate fzf and various 'frecency' plugins, including z.sh - enables easy switching between recent dirs in zsh
https://github.com/andrewferrier/fzf-z

Last synced: 3 months ago
JSON representation

Plugin for zsh to integrate fzf and various 'frecency' plugins, including z.sh - enables easy switching between recent dirs in zsh

Awesome Lists containing this project

README 

        
# fzf-z



**Note**: Personally I am no longer using this plugin actively, so I have archived it.

If you're interested in taking it over, please let me know.



---



This plugin was originally inspired as a mashup between

[fzf](https://github.com/junegunn/fzf), and oh-my-zsh's [z

plugin](https://github.com/robbyrussell/oh-my-zsh/tree/master/plugins/z),

which allows you to track recently and commonly used directories. The *z*

plugin does a great job of allowing you to switch between frequently-used

directories just by typing `z *somedirectorysubstring*`, but it doesn't really

easily allow you to browse those directories, with partial-string search. This

plugin was invented to solve that problem, using `fzf` as a front-end. Since

then, it's been extended to support [fasd](https://github.com/clvv/fasd) and

[autojump](https://github.com/wting/autojump), other 'frecency' plugins, as

alternatives to `z`.



## Installation



You can install `fzf-z` like any other `zsh` plugin. If you're not familiar

with `zsh` plugins, using a plugin manager is the easiest way to install one.

You can find information on some popular choices

[here](https://wiki.archlinux.org/index.php/Zsh#Plugin_managers). `oh-my-zsh`

and other configuration frameworks do not by themselves allow you to add custom

plugins such as `fzf-z`; you'll likely need a plugin manager in addition.



### Pre-requisites



You must have one of these installed:



* The [z

plugin](https://github.com/robbyrussell/oh-my-zsh/tree/master/plugins/z).



* The [fasd](https://github.com/clvv/fasd) tool (my personal choice, and recommended

if you are not already using one of these tools).



* The [autojump](https://github.com/wting/autojump) tool.



These tools must be in your `$PATH`. These have to be installed irrespective

of how you use `fzf-z`.



You must also have [fzf](https://github.com/junegunn/fzf) installed. You can

set the full path to `fzf` binary with environment variable `FZF_BIN_PATH`, or

it uses the one found in your `$PATH`.



*Note*: When you first use `fzf-z`, if you have configured

`FZFZ_RECENT_DIRS_TOOL` to use `z` (which is the default), it will dynamically

download `z.sh` for its own internal use. You still need to have the [z

plugin](https://github.com/robbyrussell/oh-my-zsh/tree/master/plugins/z)

installed anyway.



## Sources of information



Since the original version, I've extended `fzf-z` to support other sources of

information about the directories you might be interested in, which are all

mixed into the same list delivered through `fzf`. In priority order (the order

in which they are shown in `fzf`, first to last):



1. Directories *under* the current directory. The number of these shown in

   `fzf` is limited by the `FZFZ_SUBDIR_LIMIT` environment variable, which

   defaults to 50. If you don't want those to be shown, simply set this to

   `0`.



1. Recently used dirs. By default, these are provided by the `z` command from

   the z plugin (the original purpose of this plugin). The order shown is the

   order given by `z -l`. However, if you want to use `fasd` (preferred) or

   `autojump` instead, set `FZFZ_RECENT_DIRS_TOOL` to `fasd` or `autojump`

   respectively.



1. All subdirectories in all directories listed in the `FZFZ_EXTRA_DIRS`

   environment variables. These directories are space-separated, so for

   example:



   `export FZFZ_EXTRA_DIRS="~/MyDocuments '~/Desktop/Some Other Stuff'"`



## Ways to use fzf-z



### As a zsh plugin



Treat this plugin like any other zsh plugin and install using a [zsh plugin

manager](https://github.com/unixorn/awesome-zsh-plugins#frameworks). For

example:



Once the plugin is installed, simply hit `` on the zsh command-line,

and it will bring up a list of directories according to the sources of

information listed above. Select one, perhaps typing to filter the list, and

hit Enter - the path to the selected directory will be inserted into the

command line.  If you started with an empty command line, and you have the

`AUTO_CD` zsh option turned on you'll change to that directory instantly.



This is similar to the default **Ctrl-T** binding already provided by the

[fzf zsh key-bindings

file](https://github.com/junegunn/fzf/blob/master/shell/key-bindings.zsh). At

the moment, this plugin doesn't allow the **Ctrl-G** keybinding to be

customized, but you can change by simply forking the plugin and editing the

file if you want.



### As a command



*New*: this plugin repository also now includes `fzfz` as a standalone command

(although it depends on the provided script `recentdirs.sh` also). You can run this

as an alternative to using this as a plugin, and it will print the selected

directory to stdout, which you can use to embed this in other tools.



## Customizing and Options



If you set the `FZFZ_EXCLUDE_PATTERN` environment variable to a regex (matched

with `egrep`) it will exclude any directory which matches it from appearing in

the subdirectory results (it isn't applied to the `z`/`fasd`/`autojump`

results, since it's assumed any directory you've navigated to before is one

you might be interested in). By default this variable is set to filter out

anything in a `.git` directory.



You can also set `FZFZ_EXTRA_OPTS` to add any additional options you like to

the `fzf` command - for example, `-e` will turn exact matching on by default.



By default, fzf-z will filter out duplicates in its list so directories found

via multiple methods don't appear twice; however, this does slow it down. If

you don't care about that and want to speed it up, set

`FZFZ_UNIQUIFIER="cat"`.



If you want to change the preview command used by fzfz (currently `tree` by

default if it's installed, or `ls` if not), set `FZFZ_PREVIEW_COMMAND` to

something like `ls {}` (`{}` is replaced with the directory currently

selected).



## Performance



If it's installed and in your `PATH`, `fzf-z` will use

[fd](https://github.com/sharkdp/fd). If not, it'll fall back to `find`, which

is slower. The behaviour is slightly differently also; `fd` will exclude files

ignored by `.gitignore` or similar, which `find` will not do, so you will get

less results. Generally, this is what you want, though.