zgod

zgod

Highly customizable interactive shell history search with fuzzy, regex, and glob matching.

zgod records every command you run, stores it in a local SQLite database, and gives you an interactive search interface bound to Ctrl+R.

Install

Quick install

Unix (Linux/macOS):

curl -fsSL https://raw.githubusercontent.com/zigai/zgod/master/install.sh | sh

Windows:

irm https://raw.githubusercontent.com/zigai/zgod/master/install.ps1 | iex

Go install

go install github.com/zigai/zgod@latest

Build from source

git clone https://github.com/zigai/zgod.git
cd zgod
go build

Shell setup

The easiest way to set up zgod is to use the install command:

zgod install bash   # or zsh, fish

This will automatically add the required configuration to your shell's config file.

If you prefer to set it up manually, add one of the following to your shell configuration file:

Bash (~/.bashrc)

eval "$(zgod init bash)"

Zsh (~/.zshrc)

eval "$(zgod init zsh)"

Fish (~/.config/fish/config.fish)

zgod init fish | source

This hooks into your shell to automatically record commands and binds Ctrl+R to the interactive search.

Usage

Press Ctrl+R in your shell to open the search interface. Start typing to filter your history. Press Enter to select a command, Esc to cancel.

Keybindings

Configuration

zgod is configured via ~/.config/zgod/config.toml. All fields are optional. History is stored in a SQLite database at ~/.local/share/zgod/history.db.

[db]
path = ""  # default: ~/.local/share/zgod/history.db

[filters]
ignore_space = true       # skip commands starting with a space
exit_code = [130]         # exit codes to skip, e.g. 130 = Ctrl+C
command_glob = []         # command glob patterns to skip, e.g. ["cd *", "ls", "exit"]
command_regex = []        # command regex patterns to skip, e.g. ["^sudo "]
directory_glob = []       # directory glob patterns to skip, e.g. ["/tmp/**"]
directory_regex = []      # directory regex patterns to skip, e.g. ["^/tmp"]
max_command_length = 0    # skip commands longer than this (0 = disabled)

[theme]
prompt = "> "
prompt_color = "cyan"
match_color = "yellow"
match_bold = true
match_underline = true
match_bg = ""
selected_bg = "24"
selected_fg = ""
selection_bar_show = true
selection_bar_char = "▌ "
selection_bar_color = "14"
selection_full_line = true
mode_color = "240"
border_color = ""

[display]
time_format = "relative"       # relative | absolute
duration_format = "auto"       # auto | ms | s
show_directory = false         # show directory column in search results
hide_multiline = false         # hide multiline commands from results
multiline_preview = "popup"    # popup | preview_pane | expand | collapsed
multiline_collapse = " "       # symbol to replace newlines in collapsed view

[keys]
mode_next = "ctrl+s"
mode_fuzzy = "alt+f"
mode_regex = "alt+r"
mode_glob = "alt+g"
toggle_cwd = "ctrl+d"
toggle_dedupe = "ctrl+g"
toggle_fails = "ctrl+f"
accept = "enter"
cancel = "esc"
up = "up"
down = "down"
help = "?"
preview_command = "alt+p"