--- name: "hstr" section: "1" platform: "linux" package: "hstr" version: "3.1+ds-1+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/hstr" --- # hstr(1) easily view, navigate, sort and use your command history with shell history suggest box. ## NAME **hstr** - easily view, navigate, sort and use your command history with shell history suggest box. ## 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 .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 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 a sensitive content. ## 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 to 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 to edit it on the command prompt. - **LEFT** arrow Choose currently selected item for completion and let user to 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 site (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 rawhistory (duplicates are discarded by default). *verbose-kill*\ Print the last command 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 { { HSTR_OUT="$( { &1 1>&3 3>&- )"; } 3>&1; READLINE_LINE="$(hstr ${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 '"\C-r": "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="$( { &1 1>&3 3>&- )"; } 3>&1; BUFFER="${HSTR_OUT}" CURSOR=${#BUFFER} zle redisplay } zle -N hstr_no_tiocsti bindkey '\C-r' 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 \ ## BUGS Report bugs to https://github.com/dvorka/hstr/issues ## SEE ALSO [**history**(1)](/history/1.md), [**bash**(1)](/bash/1.md), [**zsh**(1)](/zsh/1.md)