DOCSEARCHbyAlgolia
Submit Docs

fzf-tab

repository·master·Indexed 24 days ago

https://github.com/aloxaf/fzf-tab

A Zsh plugin that replaces the default completion selection menu with an interactive fzf-based interface. It integrates with the existing Zsh completion system and includes zsh-ls-colors for file information colorization, with an optional binary module for improved performance in large directories.

Tokens
2.5K
Snippets
9
Records
11
Agent score
39%

What's inside fzf-tab

  2. Integrate zsh-ls-colors as a Git submodule

    master

    To include zsh-ls-colors as a submodule in your project, use the following commands. This is a one-time setup for adding, and a periodic process for updating.

    # Add (only once)
git submodule add git://github.com/xPMo/zsh-ls-colors.git ls-colors
git commit -m 'Add ls-colors as submodule'

# Update
cd ls-colors
git fetch
git checkout origin/master
cd ..
git commit ls-colors -m 'Update ls-colors to latest'

  3. Manage parameter namespacing and performance

    master

    The library provides several strategies for handling namecolors and modecolors parameters, depending on whether you prioritize global availability or namespace cleanliness:

    1. Global Initialization: Call ls-color::init once during load. This is fastest but pollutes the global namespace.
    2. On-demand Matching: Use ls-color::match-by $file lstat without calling init. This avoids global pollution but re-parses LS_COLORS on every call.
    3. Scoped Initialization: Call ls-color::init inside a function using local -A parameters. This is the best balance for parsing multiple filenames without polluting the global namespace.
    4. Serialization/Caching: Initialize once, serialize the modecolors and namecolors arrays to a file using typeset -p, and zcompile that file for fast loading in other functions.
    # Strategy 1: Call once when loading (Pollutes global namespace)
ls-color::init

# Strategy 2: Don't call init at all (Reparses LS_COLORS on every call)
ls-color::match-by $file lstat

# Strategy 3: Initialize within a scope with local parameters (Best for multiple filenames)
(){
	local -A namecolors modecolors
	ls-color::init

	for arg; do
	...
	done
}

# Strategy 4: Serialize to a compiled cache file
typeset -g LS_COLORS_CACHE_FILE=$(mktemp)
(){
	local -A namecolors modecolors
	ls-color::init
	typeset -p modecolors namecolors >| $LS_COLORS_CACHE_FILE
	zcompile $LS_COLORS_CACHE_FILE
}

my-function(){
	local -A namecolors modecolors
	source $LS_COLORS_CACHE_FILE

	...
}

  4. Install fzf-tab via Plugin Managers

    master

    You can install fzf-tab using several popular Zsh plugin managers:

    • Antigen
    • Zinit
    • Oh-My-Zsh (via custom directory)
    • Prezto (via contrib directory)
    ### Antigen

```zsh
antigen bundle Aloxaf/fzf-tab

    Zinit

    zinit light Aloxaf/fzf-tab

    Oh-My-Zsh

    git clone https://github.com/Aloxaf/fzf-tab ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/fzf-tab

    Prezto

    git clone https://github.com/Aloxaf/fzf-tab $ZPREZTODIR/contrib/fzf-tab

  5. Integrate zsh-ls-colors as a Git subtree

    master

    To include zsh-ls-colors as a subtree, you can either add it directly via URL or by adding a remote first. Use the --squash flag to keep your history clean.

    # Initial add (Directly via URL)
git subtree add --prefix=ls-colors/ --squash -m 'Add ls-colors as a subtree' \\git://github.com/xPMo/zsh-ls-colors.git master

# Update
git subtree pull --prefix=ls-colors/ --squash -m 'Update ls-colors to latest' \\git://github.com/xPMo/zsh-ls-colors.git master 

# --- OR, after adding a remote ---

git remote add ls-colors git://github.com/xPMo/zsh-ls-colors.git

# Initial add
git subtree add --prefix=ls-colors/ --squash -m 'Add ls-colors as a subtree' ls-colors master

# Update
git subtree pull --prefix=ls-colors/ --squash -m 'Update ls-colors to latest' ls-colors master

  6. Install fzf-tab

    master

    To use fzf-tab, ensure you have fzf installed first.

    Important Loading Order:

    1. Configure completions (as per zsh-completions guide).
    2. Run compinit.
    3. Load fzf-tab.
    4. Load plugins that wrap widgets (e.g., zsh-autosuggestions or fast-syntax-highlighting).

    If you encounter issues, ensure fzf-tab is the last plugin to bind ^I (Tab).

    ### Manual

First, clone this repository.

```zsh
git clone https://github.com/Aloxaf/fzf-tab ~/somewhere

    Then add the following line to your ~/.zshrc.

    autoload -U compinit; compinit
source ~/somewhere/fzf-tab.plugin.zsh

  8. Configure fzf-tab via zstyle

    master

    Use zstyle to customize the behavior of fzf-tab. Common configurations include disabling sorting for specific commands, setting description formats, enabling filename colorization, and adding custom fzf flags.

    Note: When setting description formats, do not use escape sequences like %F{red}%d%f, as fzf-tab will ignore them.

    # disable sort when completing `git checkout`
zstyle ':completion:*:git-checkout:*' sort false

# set descriptions format to enable group support
zstyle ':completion:*:descriptions' format '[%d]'

# set list-colors to enable filename colorizing
zstyle ':completion:*' list-colors ${(s.:.)LS_COLORS}

# force zsh not to show completion menu, which allows fzf-tab to capture the unambiguous prefix
zstyle ':completion:*' menu no

# preview directory's content with eza when completing cd
zstyle ':fzf-tab:complete:cd:*' fzf-preview 'eza -1 --color=always $realpath'

# custom fzf flags
# NOTE: fzf-tab does not follow FZF_DEFAULT_OPTS by default
zstyle ':fzf-tab:*' fzf-flags --color=fg:1,fg+:2 --bind=tab:accept

# To make fzf-tab follow FZF_DEFAULT_OPTS.
# NOTE: This may lead to unexpected behavior since some flags break this plugin.
zstyle ':fzf-tab:*' use-fzf-default-opts yes

# switch group using `<` and `>`
zstyle ':fzf-tab:*' switch-group '<' '>'

  9. Customize function namespacing for zsh-ls-colors

    master

    When sourcing the library, you can provide a custom prefix to avoid function name collisions in the global namespace. The prefix is applied to functions like init, match-by, from-name, and from-mode.

    # load functions as my-lscolors::{init,match-by,from-name,from-mode}
source ${0:h}/ls-colors/ls-colors.zsh my-lscolors

  10. Speed up colorization with the Binary Module

    master

    By default, fzf-tab uses a pure Zsh script (zsh-ls-colors) to parse and apply LS_COLORS. This can be slow for large directories. To improve performance, you can build the provided binary module. Once built, it will be enabled automatically.

    build-fzf-tab-module

  11. Use fzf-tab keybindings and commands

    master

    Once installed, press <kbd>Tab</kbd> to trigger the fzf-based completion menu.

    Keybindings:

    • <kbd>Ctrl</kbd>+<kbd>Space</kbd>: Select multiple results (configurable via fzf-bindings tag).
    • <kbd>F1</kbd> / <kbd>F2</kbd>: Switch between groups (configurable via switch-group tag).
    • /: Trigger continuous completion (useful for deep paths; configurable via continuous-trigger tag).

    Commands:

    • disable-fzf-tab: Disable fzf-tab and fallback to standard compsys.
    • enable-fzf-tab: Enable fzf-tab.
    • toggle-fzf-tab: Toggle the state of fzf-tab (this is also a ZLE widget).