Replace zsh's default completion selection menu with fzf!
Table of Contents
- fzf-tab
- Install
- Usage
- Difference from other plugins
- Compatibility with other plugins
- Related projects
【中文文档】
NOTE: fzf-tab needs to be sourced after compinit
, but before plugins which will wrap widgets like zsh-autosuggestions or fast-syntax-highlighting.
First, clone this repository
git clone https://github.com/Aloxaf/fzf-tab ~/somewhere
Then add the following line to your ~/.zshrc
source ~/somewhere/fzf-tab.plugin.zsh
antigen bundle Aloxaf/fzf-tab
zinit light Aloxaf/fzf-tab
Clone this repository to your custom directory and then add fzf-tab
to your plugin list.
git clone https://github.com/Aloxaf/fzf-tab ~ZSH_CUSTOM/plugins/fzf-tab
Just press Tab as usual~
You can use Ctrl+Space to select multiple results, and / to trigger continuous completion (useful when complete a deep path).
Available commands:
-
disable-fzf-tab
: Use it when you come across some bugs -
enable-fzf-tab
: Use it when fzf-tab doesn't initialize properly.
Key Bindings:
toggle-fzf-tab
: Use it disable/enable plugin.
For example Ctrl+T bindkey '^T' toggle-fzf-tab
fzf-tab use zstyle for configuration. It can give you more control over fzf-tab's behavior, eg:
# disable sort when completing options of any command
zstyle ':completion:complete:*:options' sort false
# use input as query string when completing zlua
zstyle ':fzf-tab:complete:_zlua:*' query-string input
# (experimental, may change in the future)
# some boilerplate code to define the variable `extract` which will be used later
# please remember to copy them
local extract="
# trim input(what you select)
local in=\${\${\"\$(<{f})\"%\$'\0'*}#*\$'\0'}
# get ctxt for current completion(some thing before or after the current word)
local -A ctxt=(\"\${(@ps:\2:)CTXT}\")
# real path
local realpath=\${ctxt[IPREFIX]}\${ctxt[hpre]}\$in
realpath=\${(Qe)~realpath}
"
# give a preview of commandline arguments when completing `kill`
zstyle ':completion:*:*:*:*:processes' command "ps -u $USER -o pid,user,comm,cmd -w -w"
zstyle ':fzf-tab:complete:kill:argument-rest' extra-opts --preview=$extract'ps --pid=$in[(w)1] -o cmd --no-headers -w -w' --preview-window=down:3:wrap
# give a preview of directory by exa when completing cd
zstyle ':fzf-tab:complete:cd:*' extra-opts --preview=$extract'exa -1 --color=always $realpath'
fzf-tab is configured via command like this: zstyle ':fzf-tab:{context}' tag value
. fzf-tab
is the top context.
See zsh's doc for more information.
You can use C-x h to get possible context for a command:
NOTE: You need to use enable-fzf-tab
to active fzf-tab again after this command.
❯ rg -- # Press `C-x h` here
tags in context :completion::complete:rg::
operand-argument-1 options (_arguments _rg _ripgrep)
tags in context :completion::complete:rg:options:
options (_arguments _rg _ripgrep)
tags in context :completion::files-enhance:::
globbed-files (_files _files_enhance)
Here are avaiable tags in fzf-tab
context:
How to start the fuzzy search program.
Default value:
FZF_TAB_COMMAND=(
fzf
--ansi # Enable ANSI color support, necessary for showing groups
--expect='$continuous_trigger,$print_query' # For continuous completion and print query
'--color=hl:$(( $#headers == 0 ? 108 : 255 ))'
--nth=2,3 --delimiter='\x00' # Don't search prefix
--layout=reverse --height='${FZF_TMUX_HEIGHT:=75%}'
--tiebreak=begin -m --bind=tab:down,btab:up,change:top,ctrl-space:toggle --cycle
'--query=$query' # $query will be expanded to query string at runtime.
'--header-lines=$#headers' # $#headers will be expanded to lines of headers at runtime
--print-query
)
zstyle ':fzf-tab:*' command $FZF_TAB_COMMAND
Extra options for command
Default value: None
The key to trigger a continuous completion. It's useful when complete a long path.
Default value: zstyle ':fzf-tab:*' continuous-trigger '/'
Press this key to use current user input as final completion result.
Default value: zstyle: ':fzf-tab:*' print-query alt-enter
Don't activate fzf-tab in this context. If it is a number, then fzf-tab won't be activated if the number of candidates is smaller than this number.
Default value: zstyle ':fzf-tab:*' ignore false
How to do a fake compadd. This only affects the result of multiple selections.
default
: Call compadd with an empty string. It will sometimes add extra whitespace if you select multiple results.fakeadd
: Try to deceive the completion system. Sometimes it fails and then leads to unwanted results. (eg.sudo git \t
will get not only git subcommands but also local files)
Default value: zstyle ':fzf-tab:*' fake-compadd default
Whether to automatically insert a space after the result.
Default value: zstyle ':fzf-tab:*' insert-space true
The strategy for generating query string.
Possible values:
input
: use user's input as query string, just like zsh's default behaviorprefix
: use the longest common prefix for all candidates as the query stringfirst
: just a flag. If set, the first valid query string will be usedlongest
: another flag. If set, the longest valid query string will be used
Default value: zstyle ':fzf-tab:*' query-string prefix input first
A prefix to indicate the color.
Default value: zstyle ':fzf-tab:*:' prefix '·'
NOTE: If not set zstyle ':completion:*:descriptions' format
, it will be set to empty.
Color when there is no group.
Default value: zstyle ':fzf-tab:*' no-group-color $'\033[37m'
(white)
What to show when there is only one group.
Possible values:
prefix
: show color prefixcolor
: show group colorheader
: show group header
Default value: zstyle ':fzf-tab:*' single-group color header
Color for different groups and their descriptions.
Default value:
FZF_TAB_GROUP_COLORS=(
$'\033[94m' $'\033[32m' $'\033[33m' $'\033[35m' $'\033[31m' $'\033[38;5;27m' $'\033[36m' \
$'\033[38;5;100m' $'\033[38;5;98m' $'\033[91m' $'\033[38;5;80m' $'\033[92m' \
$'\033[38;5;214m' $'\033[38;5;165m' $'\033[38;5;124m' $'\033[38;5;120m'
)
zstyle ':fzf-tab:*' group-colors $FZF_TAB_GROUP_COLORS
To choose the color you want, you can first use this function to print the palette:
# Usage: palette
palette() {
local -a colors
for i in {000..255}; do
colors+=("%F{$i}$i%f")
done
print -cP $colors
}
And then use this helper function to get escape sequence for the color code:
# Usage: printc COLOR_CODE
printc() {
local color="%F{$1}"
echo -E ${(qqqq)${(%)color}}
}
When zstyle ':completion:*:descriptions' format
is set, fzf-tab will display these group descriptions as headers.
Set to full
to show all descriptions, set to brief
to only show descriptions for groups with duplicate members.
Default value: zstyle ':fzf-tab:*' show-group full
By default, fzf-tab use zsh-ls-colors to parse and apply ZLS_COLORS if you have enable list-colors
tag.
However, this is a pure zsh script and is slow if you have too many files to colorize.
fzf-tab is shipped with a binary module to speed up this process. You can build it with build-fzf-tab-module
, then it will be enabled automatically.
fzf-tab doesn't do "complete", it just shows your results of the default completion system.
So it works EVERYWHERE (variables, function names, directory stack, in-word completion, etc.). And most of your configure for default completion system is still valid.
Some plugins may also bind "^I" to their custom widget, like fzf/shell/completion.zsh or ohmyzsh/lib/completion.zsh.
By default, fzf-tab will call the widget previously bound to "^I" to get the completion list. So there is no problem in most cases, unless fzf-tab is initialized before a plugin which doesn't handle the previous binding properly.
So if you find your fzf-tab doesn't work properly, please make sure it is the last plugin to bind "^I" (If you don't know what I mean, just put it to the end of your plugin list).
- https://github.com/lincheney/fzf-tab-completion (fzf tab completion for zsh, bash and GNU readline apps)