Documentation

Installation

Ubuntu

HSTR is included in Ubuntu 21.10 and newer releases:

sudo apt install hstr

For Ubuntu 21.04 and older:

sudo add-apt-repository ppa:ultradvorka/ppa
sudo apt-get update
sudo apt-get install hstr

Debian/Mint

HSTR is included in Debian 11 and newer:

sudo apt install hstr

Fedora/RHEL/CentOS

sudo dnf install hstr

or

sudo yum install hstr

macOS

Install using Homebrew:

brew install hstr

Or using MacPorts:

sudo port install hstr

Arch Linux

yaourt -S hstr-git

Build from Source

git clone https://github.com/dvorka/hstr.git
cd hstr/build/tarball
./tarball-automake.sh
cd ../..
./configure && make && sudo make install

Configuration

Configure HSTR automatically by running:

# For Bash
hstr --show-bash-configuration >> ~/.bashrc
source ~/.bashrc

# For Zsh
hstr --show-zsh-configuration >> ~/.zshrc
source ~/.zshrc

Bash Binding

Bind HSTR to Ctrl-r for Bash Emacs keymap:

bind '"\C-r": "\C-a hstr -- \C-j"'

For Bash Vim keymap:

bind '"\C-r": "\e^ihstr -- \n"'

Zsh Binding

Bind HSTR to Ctrl-r for Zsh:

bindkey -s "\C-r" "\C-a hstr -- \C-j"

HSTR Config Options

Configure HSTR using the HSTR_CONFIG environment variable with comma-separated options:

Colors

export HSTR_CONFIG=hicolor        # Use colors
export HSTR_CONFIG=monochromatic  # Black and white

Positioning

export HSTR_CONFIG=prompt-bottom          # Prompt at bottom
export HSTR_CONFIG=help-on-opposite-side  # Help on opposite side
export HSTR_CONFIG=hide-basic-help        # Hide basic help
export HSTR_CONFIG=hide-help              # Hide all help

Default View

export HSTR_CONFIG=raw-history-view  # Normal history
export HSTR_CONFIG=favorites-view    # Favorites view

Filtering

export HSTR_CONFIG=regexp-matching     # Regex matching
export HSTR_CONFIG=substring-matching  # Substring matching
export HSTR_CONFIG=keywords-matching   # Keywords (default)
export HSTR_CONFIG=case-sensitive      # Case sensitive

Other Options

export HSTR_CONFIG=static-favorites         # Static favorites
export HSTR_CONFIG=skip-favorites-comments  # Skip comments
export HSTR_CONFIG=blacklist                # Enable blacklist
export HSTR_CONFIG=no-confirm               # No delete confirm
export HSTR_CONFIG=verbose-kill             # Verbose delete
export HSTR_CONFIG=duplicates               # Keep duplicates

Combining Options

export HSTR_CONFIG=hicolor,case-sensitive,prompt-bottom

Usage

Invoking HSTR

Press Ctrl-r to invoke HSTR (if configured). Or run hstr directly:

hstr        # Standard mode
hstr -k     # Kill last command
hh          # If you created an alias

Searching History

Start typing to filter your command history. HSTR supports multiple search modes:

• Keywords - Default mode, order doesn't matter
• Substring - Match continuous strings
• Regex - Regular expression matching

Managing Favorites

• Press Ctrl-f to add/remove favorites
• Press Ctrl-/ to toggle between history and favorites
• Favorites are stored in ~/.hstr_favorites

Deleting History

• Navigate to a command and press DEL or Ctrl-d
• Confirm deletion when prompted

Keyboard Shortcuts

Environment Variables

History Settings

Increase history size for better results:

# Bash
export HISTFILESIZE=10000
export HISTSIZE=${HISTFILESIZE}
shopt -s histappend
export PROMPT_COMMAND="history -a; history -n; ${PROMPT_COMMAND}"

# Hide commands with leading space
export HISTCONTROL=ignorespace

# Zsh
export HISTFILE=~/.zsh_history
export HISTSIZE=10000
export SAVEHIST=${HISTSIZE}
setopt HIST_IGNORE_SPACE

HSTR Variables

• HISTFILE - History file location
• HSTR_CONFIG - HSTR configuration options
• HSTR_PROMPT - Custom prompt (default: user@hostname$)
• HSTR_IS_SUBSHELL - Set to 1 when in subshell

Troubleshooting

Commands Not Inserted to Terminal

This is a common issue with Linux kernel >= 6.2.0, WSL, and Cygwin due to TIOCSTI restrictions.

History Not Showing

Check your history file:

echo $HISTFILE
cat $HISTFILE | wc -l

Make sure history is being saved:

# For Bash
shopt -s histappend
export PROMPT_COMMAND="history -a; history -n; ${PROMPT_COMMAND}"

HSTR Not Found After Installation

Make sure the installation directory is in your PATH:

which hstr
echo $PATH

Colors Not Working

Ensure your terminal supports colors and configure HSTR:

export HSTR_CONFIG=hicolor