Command History

Command History

shed uses an sqlite database to store your command history. While this is slightly heavier than the usual flat text file approach used by shells like bash and zsh, it has several advantages:

• All open shed instances read from and write to the same history in real time - commands entered in one terminal are immediately available in all the others via hist --pull or Ctrl + R history searching.
• Power users can query the database directly with any SQLite tool for custom analysis, rather than needing a custom history file parser
• Each entry stores timestamp, working directory, runtime duration in milliseconds, and exit code.
• Safe writes: SQLite's transaction model means a hard kill mid-write won't leave your history file in a broken state.

hist builtin

The hist builtin provides tooling for querying the history database for specific commands. The builtin uses flags that can be composed with one another to create pseudo-SQL queries. The flags are outlined below:

Flag	Returns
--after <time>	Commands executed after the given time.
--before <time>	Commands executed before the given time.
--contains <str>	Commands that contain the given sub-string.
--starts-with <str>	Commands that start with the given string.
--ends-with <str>	Commands that end with the given string.
--matches <regex>	Commands that match the given regex pattern.
--duration-gt <dur>	Commands that took longer than the given duration.
--duration-lt <dur>	Commands that took less time than the given duration.
--lines-gt <num>	Commands that contain more than the given number of lines.
--lines-lt <num>	Commands that contain less than the given number of lines.
--with-status <code>	Commands that exited with the given exit code.
--with-token <uuid>	Commands that are stored with the given UUID.
--in-dir <dir>	Commands that were executed in the given directory.
--limit <num>	Limit the number of results returned.

Notes on the expected shape of the flag arguments:

• <time> and <dur> can be abstract times/durations like "2 days ago" or "30 minutes", or they can be absolute times/durations like "2024-01-01 12:00:00" or "1h30m". The builtin will attempt to parse the argument into a valid time/duration.
• <regex> uses the Rust regex crate syntax
• <uuid> expects a v4 UUID string. The "token" it refers to is the unique identifier that is attached to each command when it is stored in the database.

Additionally, the --not flag can be used to negate the next flag. For example, hist --not --contains "ls" will return all commands that do not contain the string "ls".

The hist builtin's other flags are

Flag	Returns
--delete	Deletes commands that match the given query. Prints the commands that were deleted, along with the count
--restore	Restores commands that were previously deleted. This only works on the most recent deletion.
--import <src>	Import command history from another shell.
--ex	Operate on ex-mode history instead of shell command history.
--pull	Pulls the latest history from the database and updates the internal "timeline".

Importing Command History

As noted above, the hist builtin supports importing history from known existing shell history formats. shed currently supports importing shell history from bash, zsh, and fish. The hist command's --import <src> flag can take either a shell name, or a literal path to a file as arguments. When given a shell name, it will check that shell's default location for the history file. When given a file, it will attempt to identify the format and then deserialize if it is well formed.

Using History

Navigating your command history can be done in several ways. There is the usual up/down arrow key navigation and Ctrl+R command searching, but shed also supports some other methods:

• ! - The ! character can be used to recall commands from history. For example, !ls will recall the most recent command that started with ls. !! recalls the last command, and !-2 recalls the second-to-last command. !$ recalls the last argument of the previous command, and !* recalls all arguments of the previous command. Submitting the command will expand it in the prompt so you can see what's actually about to get executed before you submit it.
• Autosuggestion - as you type, shed will suggest commands from your history that match what you've typed so far. You can accept the suggestion by pressing the right arrow key or Ctrl+S. You can also incrementally accept suggestions in normal mode by moving the cursor into the ghost text.
• History Join - Holding Ctrl/Shift as you navigate up and down your command history with the arrow keys will alter the behavior of the navigation: instead of fully replacing the buffer content, consecutive commands will be joined into a single command at a separator. Ctrl joins the commands with ;, and Shift joins them with &&. This allows you to quickly turn a sequence of commands into a single one.