😎

Zfzf

zfzf is a fzf-based file picker for zsh which allows you to quickly navigate the directory hierarchy

b0o
|
13 stars
2 forks

zfzf version license: MIT

Zsh + fzf

Demo

demonstration screencast

Install

# zinit
zinit light b0o/zfzf

Usage

zfzf can work in three ways:

  • as a standalone utlity by running the zfzf command
  • as a ZLE (zsh line editor) plugin via a keyboard shortcut
  • as a Zsh completion for file paths (experimental and buggy)

As a standalone utility

zfzf can be invoked by running the zfzf command and optionally passing a path as the first argument. The result will be printed to stdout.

As a ZLE plugin

By default, zfzf is mapped to Alt-period. If your cursor is adjacent to any non-whitespace text when you trigger zfzf, it will attempt to interpret that text as a path.

As a Zsh completion function

If you would like to use zfzf to complete filenames when you press tab, you should call the enable-zfzf-tab function in your .zshrc.

If you use other completion plugins like fzf-tab, you should call enable-zfzf-tab after all other plugins have been loaded and enabled, otherwise another plugin may override zfzf.

You can later call disable-zfzf-tab to restore the prior completion function.

zfzf v0.2.0

zfzf is a fzf-based file picker for zsh which allows you to easily navigate the
directory hierarchy and pick files using keybindings.

zfzf can be used as a standalone program, as an explicit zle widget, and as a
file path completion. By default, zfzf can be explicitly triggered with Alt-.
(this is configurable with the ZFZF_ZSH_BINDING option).

If you would like to use zfzf as your file completion when you press tab, you
should call the enable-zfzf-tab function in your .zshrc. If you use other
completion plugins like fzf-tab, you should call enable-zfzf-tab after all
other plugins have been loaded and enabled. You can later call disable-zfzf-tab
to restore the prior completion function.

Configuration Options
  Environment Variable          Default Value

  ZFZF_ENABLE_COLOR             1
    When enabled, files and previews will be colorized.

  ZFZF_ENABLE_PREVIEW           1
    When enabled, the focused item will be displayed in the fzf preview window.

  ZFZF_ENABLE_DOT_DOTDOT        1
    When enabled, display '.' and '..' at the top of the file listing.

  ZFZF_ZSH_BINDING              ^[. (Alt-.)
    Sets the keybinding sequence used to trigger zfzf. If set to the empty
    string, zfzf will not be bound. You can create a keybinding yourself by
    binding to the zfzf zle widget. See zshzle(1) for more information on key
    bindings.

  ZFZF_ENABLE_BAT               2
  ZFZF_ENABLE_EXA               2
    These options control zfzf's use of non-standard programs. Valid values
    include:
      - 0: Disable program
      - 1: Enable program (Force)
      - 2: Enable program (Optional)
    If the value 2 is used, the program will be enabled only if it is found in
    the PATH or if its path is explicitly specified as described below.

  ZFZF_BAT_PATH                 None
  ZFZF_EXA_PATH                 None
    These options allow paths to non-standard programs to be manually
    specified.

Default Key Bindings

  return             accept final
  alt-return         accept final (return absolute path)
  esc                escape
  ctrl-g             escape (return absolute path)
  alt-o              accept query
  ctrl-d             accept query final
  alt-P              append query
  ctrl-o             replace query
  alt-i              descend into directory or accept file
  alt-.              descend into directory or accept file
  alt-u              ascend into parent directory
  alt->              ascend into parent directory
  alt-U              ascend to next existing ancestor

TODO

  • [ ] configurable options
  • [ ] fzf key bindings
  • [ ] sorting
  • [ ] filtering
  • [x] color
  • [ ] fzf options

License

© 2021 Maddison Hellstrom

Released under the MIT License.