dirbrowse

Zsh plugin for browsing through the directory stack. This is a custom version of the dircycle plugin included in Oh My Zsh. This custom version enables browsing the parent directory and remaps the original keybindings. The default keybindings are designed for use in iTerm2 on macOS, however they can easily be changed as shown here.

This plugin enables directory navigation similar to using back and forward on any common browser or file explorer. It enables changing the current working directory within the same line of the terminal by pressing a special key combination. Users can quickly navigate through the directory stack left and right using Shift + Left / Shift + Right, or move to the parent directory by pressing Shift + Up. This operation ensures a faster workflow and minimizes clutter in the terminal by redrawing the current line. When switching directory, the current input buffer is also preserved.

Enabling the plugin

(Using Oh-my-zsh)

1. Clone this repository in oh-my-zsh's plugins directory:

git clone https://github.com/giovannilupi/dirbrowse.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/dirbrowse

2. Open your .zshrc file and add dirbrowse in the plugins section:

plugins=(
   # all your enabled plugins
   dirbrowse
)

3. Restart the shell or source your shell configuration file:

source ~/.zshrc

Usage Examples

Let's consider this sequence of operations on the terminal:

~$ cd projects
~/projects$ cd plugins
~/projects/plugins$ cd dirbrowse
~/projects/plugins/dirbrowse$ dirs -v
0       ~/projects/plugins/dirbrowse
1       ~/projects/plugins
2       ~/projects
3       ~

Pressing Shift + Left, we can move the current working directory ($CWD) to the previously visited one, going from dirbrowse to plugins. Using Shift + Up, we can go to the parent directory projects. In a symmetrical way, pressing Shift + Right moves the $CWD back from projects to plugins. Pressing it again, we can move back to dirbrowse.

Here's an example history table with the same accessed directories as above:

Current $CWD	Key press	New $CWD
dirbrowse	Shift + Left	plugins
plugins	Shift + Up	projects
projects	Shift + Left	plugins
plugins	Shift + Left	~
~	Shift + Right	plugins
plugins	Shift + Right	projects
projects	Shift + Right	plugins
plugins	Shift + Right	dirbrowse
dirbrowse	Shift + Right	~

Note the last traversal, when pressing Shift + Right on a last known $CWD, it will change back to the first known $CWD, which in the example is ~.

Here is a GIF demonstrating the example above:

Rebinding keys

You can bind these three directory browsing functions to other key sequences, as long as you know the bindkey sequence. This ensures compatibility on other systems. To do that, simply update the last three lines of dirbrowse.plugin.zsh with the desired sequences.

You can obtain a bindkey sequence by pressing Ctrl + V, then pressing the keyboard shortcut you wish to use. As an alternative, you can use:

showkey -a

or:

cat -v