Skip to content

Configuration

Michał Nowotnik edited this page Jun 20, 2022 · 16 revisions

Keybindings

By default you need to press Ctrl-n to run fzshell. However, you can change it with the environment variable $FZSHELL_BIND_KEY. Take into account that bash and zsh have different syntax for keybinding.

bash

Default value for keybinding is \C-n. To set binding to Ctrl-x, add this line to .bashrc:

export FZSHELL_BIND_KEY="\C-x"

zsh

Default value for keybinding is ^n. To set binding to Ctrl-x, add this line to .zshrc:

export FZSHELL_BIND_KEY="^x"

fish

Default value for keybinding is \cn. To set binding to Ctrl-x, add this line to config.fish:

export FZSHELL_BIND_KEY="\cx"

fzshell.yaml

The root of configuration file can contain only one element:

  • completions

completions

completions is a list of completion definition objects.

completions:
  - pattern: 'cat (\w+\.json) \| jq (\..*)'
    cmd: 'jq $2 $1 | jq keys | jq  ". []"'
    map: '{{ ternary (printf ".%s" .item) (printf "[%s]" .item) (hasPrefix "\"" .item) }}'
    preview: >
      jq -C '{{._2}}[{{.item}}]'  {{._1}}

  - pattern: "jq '?(\\.[^']*)'? (\\w+.json)"
    replacement: jq '{{._1}}[{{ .item }}]' {{._2}}
    cmd: 'jq $1 $2 | jq keys | jq  ". []"'
    preview: jq -C '{{._1}}[{{.item}}]'  {{._2}}

  - pattern: "docker rm"
    cmd: "docker ps -a --format '{{.Names}}\t{{.ID}}\t{{.Image}}\t{{.Status}}'"
    map: ' {{ .item | split "\t" | mapGet "_0" }}'

pattern

pattern field MUST be defined for a definition to be valid. It contains a string value that is used as a golang regular expression to match against line buffer. It can contain subexpressions ((foo)) and named subexpressions ((?P<foo>bar)). Text matched by those expressions can be referenced by chosen names (foo) in the case of named subexpressions or indices preceded by an underscore (_1).

⚠️ Pattern by default matches the end of a string. "$" is added at the end of a pattern. Keep that in mind when writing new patterns. If you think this behavior is unintuitive, hard to live with, and you have better idea, make a feature request.

replacement

Optional field. Go template that has access to pattern capture groups. Its input is item variable that is returned from a map expression if available or cmd otherwise. Must return a string.

selectOne

Optional field. A bool variable that will cause fzshell to immediately return the only completion.

itemSeparator

Optional field. Single space character (" ") by default. A string used to separate multiple completion entries. For example if you choose entries A,B,C, you will see string "AxBxC" returned if itemSeparator is set to "x".

cmd

Optional field. It is a shell expression that will be evaluated by Bash to generate completions. If cmd is not defined, the line buffer will be simply replaced by replacement if available.

map

Optional field. Go template that has access to pattern capture groups. Its input is item variable that is a single line from the text returned by the cmd expression. Must return a string.

preview

Optional field. Should return a string that is a Bash command to show the preview of an item. Has access to item variable and similarly to pattern capture groups. The result of a preview command is shown in the window on the right side.

headerLines

Integer. Described how many lines of the cmd output should be treated as header.

header

String or list of strings. Sticky header that is at the bottom row.

Clone this wiki locally