HSTR(1)

📦
version 3.2 · 5 versions
, in alpine 3.24, nixpkgs unstable

🌸 NAME 🌸 — hstr from the General Commands Manual (HSTR(1)) 💅

hstr — easily view, navigate, sort and use your command history with a shell history suggest box. That’s the whole NAME vibe, bestie. 🫶

✨ SYNOPSIS ✨

hstr [option] [arg1] [arg2]...

🦋 DESCRIPTION 🦋

hstr uses shell history to provide suggest box like functionality for commands used in the past. By default it parses the .bash-history file that is filtered as you type a command substring. Commands are not just filtered, but also ordered by a ranking algorithm that considers the number of occurrences, length and timestamp. Favorite and frequently used commands can be bookmarked. In addition hstr allows removal of commands from history — for instance with a typo or with sensitive content. No cap, it’s giving history glow-up. 👑

💖 OPTIONS 💖

  • -h, --help — show help 💬
  • -n, --non-interactive — print filtered history on standard output and exit 📤
  • -k, --kill-last-command — delete the last command from history and exit 💀
  • -i, --insert-in-terminal=[command] — insert custom command in terminal prompt and exit ✍️
  • -f, --favorites — show favorites view immediately ⭐
  • -s, --show-configuration — show configuration to be added to the config file of the shell (~/.bashrc or ~/.zshrc) 🛠️
  • -B, --show-bash-configuration — show Bash configuration to be added to ~/.bashrc 🐚
  • -Z, --show-zsh-configuration — show Zsh configuration to be added to ~/.zshrc 🌊
  • -b, --show-blacklist — show blacklist of commands to be filtered out before history processing 🚫
  • -V, --version — show version information 🏷️

🎀 KEYS 🎀

  • pattern — type to filter shell history. 🔎
  • Ctrl-e — toggle regular expression and substring search. 🔁
  • Ctrl-t — toggle case sensitive search. 🔠
  • Ctrl-/, Ctrl-7 — rotate view of history as provided by bash, ranked history ordered by the number of occurrences/length/timestamp and favorites. 🎡
  • Ctrl-f — add currently selected command to favorites. 💖
  • Ctrl-l — toggle search pattern case. 🔄
  • Ctrl-r, UP arrow, DOWN arrow, Ctrl-n, Ctrl-p, Ctrl-j, Ctrl-k — navigate in the history list. 🧭
  • TAB, RIGHT arrow — choose currently selected item for completion and let user edit it on the command prompt. ➡️
  • LEFT arrow — choose currently selected item for completion and let user edit it in editor (fix command). ⬅️
  • ENTER — choose currently selected item for completion and execute it. 🚀
  • DEL — remove currently selected item from the shell history. 🗑️
  • BACKSPACE, Ctrl-h — delete last pattern character. ⌫
  • Ctrl-u, Ctrl-w — delete pattern and search again. 🧹
  • Ctrl-x — write changes to shell history and exit. 💾
  • Ctrl-g — exit with empty prompt. 👋

🌈 ENVIRONMENT VARIABLES 🌈

hstr defines the following environment variables:

🌟 HSTR_CONFIG 🌟

Configuration options:

  • hicolor — get more colors with this option (default is monochromatic). 🎨
  • monochromatic — ensure black and white view. 🖤
  • prompt-bottom — show prompt at the bottom of the screen (default is prompt at the top). ⬇️
  • help-on-opposite-side — show help label on the opposite side (default is next to the prompt). ↔️
  • hide-basic-help — hide the basic help label. 🙈
  • hide-help — hide basic and history help labels. Implicitly sets hide-basic-help. 🙊
  • no-confirm — do not ask for confirmation on a history entry delete (default is with confirmation). ✅
  • regexp-matching — filter command history using regular expressions. 🧪
  • substring-matching — filter command history using substring. 🧵
  • keywords-matching — filter command history using keywords — item matches if contains all keywords in pattern in any order (keywords match is default). 🔑
  • case-sensitive — make history filtering case sensitive (it’s case insensitive by default). 🔡
  • raw-history-view — show normal history as a default view (metric-based view is shown otherwise). 📜
  • favorites-view — show favorites as a default view (metric-based view is shown otherwise). 💫
  • static-favorites — do not put recently used favorite to the head of favorites (favorites are reordered by default). 📌
  • skip-favorites-comments — skip comments (lines beginning with #) when loading ~/.hstr_favorites (all lines are loaded by default). 💬
  • duplicates — show duplicates in raw history (duplicates are discarded by default). 👯
  • verbose-kill — print the last command deleted from history (nothing is printed by default). 📣
  • blacklist — load list of commands to skip when processing history from ~/.hstr_blacklist (built-in blacklist used otherwise). 🚫
  • keep-page — don’t clear page with command selection on exit (page is cleared by default). 📄
  • big-keys-skip — skip big history entries i.e. very long lines (default). 🦣
  • big-keys-floor — use different sorting slot for big keys when building metrics-based view (big keys are skipped by default). 🏗️
  • big-keys-exit — exit (fail) on presence of a big key in history (big keys are skipped by default). 💥
  • warning — show warning. ⚠️
  • debug — show debug information. 🐞

Example:

export HSTR_CONFIG=hicolor,regexp-matching,raw-history-view

🌟 HSTR_PROMPT 🌟

Change prompt string which is user@host$ by default.

Example:

export HSTR_PROMPT="$ "

🌸 FILES 🌸

  • ~/.hstr_favorites — bookmarked favorite commands. ⭐
  • ~/.hstr_blacklist — commands to be hidden. 🙈

🐚 BASH CONFIGURATION 🐚

Add the following lines to ~/bashrc if TIOCSTI is not supported by your OS:

alias hh=hstr                    # hh to be alias for hstr
export HSTR_CONFIG=hicolor       # get more colors
shopt -s histappend              # append new history items to .bash_history
export HISTCONTROL=ignorespace   # leading space hides commands from history
export HISTFILESIZE=10000        # increase history file size (default is 500)
export HISTSIZE=${HISTFILESIZE}  # increase history size (default is 500)
# ensure synchronization between bash memory and history file
export PROMPT_COMMAND="history -a; history -n; ${PROMPT_COMMAND}"
function hstrnotiocsti {
    { READLINE_LINE=
    READLINE_POINT=${#READLINE_LINE}
}
# if this is interactive shell, then bind hstr to Ctrl-r (for Vi mode check doc)
if [[ $- =~ .*i.* ]]; then bind -x '""hstrnotiocsti"'; fi
export HSTR_TIOCSTI=n

Optionally add the following lines to ~/.bashrc if TIOCSTI is supported by your OS:

alias hh=hstr                    # make hh alias of hstr
export HSTR_CONFIG=hicolor       # get more colors
shopt -s histappend              # append new history items to .bash_history
export HISTCONTROL=ignorespace   # leading space hides commands from history
export HISTFILESIZE=10000        # increase history file size (default is 500)
export HISTSIZE=${HISTFILESIZE}  # increase history size (default is 500)
# ensure synchronization between bash memory and history file
export PROMPT_COMMAND="history -a; history -n; ${PROMPT_COMMAND}"
# if this is interactive shell, then bind hstr to Ctrl-r (for Vi mode check doc)
if [[ $- =~ .*i.* ]]; then bind '"\C-r": "\C-a hstr -- \C-j"'; fi

🌊 ZSH CONFIGURATION 🌊

Add the following lines to ~/zshrc if TIOCSTI is not supported by your OS:

alias hh=hstr                    # hh to be alias for hstr
setopt histignorespace           # skip cmds w/ leading space from history
export HSTR_CONFIG=hicolor       # get more colors
hstr_no_tiocsti() {
    zle -I
    { HSTR_OUT="$( { </dev/tty hstr -- ${BUFFER}; } 2>&1 1>&3 3>&- )"; } 3>&1;
    BUFFER="${HSTR_OUT}"
    CURSOR=${#BUFFER}
    zle redisplay
}
zle -N hstr_no_tiocsti
bindkey 'hstr_no_tiocsti
export HSTR_TIOCSTI=n

Optionally add the following lines to ~/.zshrc if TIOCSTI is supported by your OS:

export HSTR_CONFIG=hicolor            # get more colors
setopt histignorespace                # skip cmds w/ leading space from history
bindkey -s "\C-r" "\C-a hstr -- \C-j" # bind hstr to Ctrl-r (for Vi mode check doc)

🍓 EXAMPLES 🍓

  • hstr git — start hstr and show only history items containing 'git'. 🔎
  • hstr cpp add git — start hstr and show only history items containing 'cpp', 'add' and 'git'. 🔎
  • hstr --non-interactive git — print history items containing 'git' to standard output and exit. 📤
  • hstr --show-configuration >> ~/.bashrc — append default hstr configuration to your Bash profile. 🐚
  • hstr --show-configuration >> ~/.zhrc — append default hstr configuration to your Zsh profile. 🌊
  • hstr --show-blacklist — show blacklist configured for history processing. 🚫
  • hstr --insert-in-terminal="git add . && git diff --cached" — insert command in terminal prompt and exit. ✍️

👑 AUTHOR 👑

Written by Martin Dvorak <martin.dvorak@mindforger.com> 💌

💀 BUGS 💀

Report bugs to https://github.com/dvorka/hstr/issues 🐞

🧚 SEE ALSO 🧚

history(1), bash(1), zsh(1) 🫶

💜 okay bestie, that’s the whole HSTR(1) page. The footer just says HSTR(1) — no extra source/version/date tea in this copy, so that’s all she wrote, periodt. 🎀✨

📦 where this page comes from