Complete Shell Navigation: better up, z, and h

Easily navigate to parent directories, recent directories, repos, and more.

This project aims to provide improved versions of utilities like up, bd, z, autojump, and h, with fzf as the selection engine/interface.

Use cases

When navigating in the shell, 99% of the time I want to do one of the following:

• Go up to a parent directory
  • Provided by compnav's up function (can be renamed to whatever you want).
• Jump to a recent directory
  • Provided by compnav's z function (can be renamed to whatever you want).
• Jump to a repo
  • Provided by compnav's h function (can be renamed to whatever you want).
• Go down to a child subdir
  • Already provided by fzf's Alt-C (but see improved config below that uses bfs).
• Easily select from command history
  • Already provided by fzf's Ctrl-R

Installation / Setup

Prerequisites

You will need:

1. fzf (it's great, please consider sponsoring ❤️ them!)
2. Ruby 2.6 or newer.

Installation

1. Clone this repo somewhere, like ~/bin.

2. Add the following to .bashrc/.zshrc, setting the required variables appropriately:

# REQUIRED:
export COMPNAV_DIR="$HOME/bin/compnav"
export COMPNAV_H_REPOS_DIR="$HOME/Repos"

[ -f "$COMPNAV_DIR/compnav.sh" ] && source "$COMPNAV_DIR/compnav.sh"

3. NOTE: make sure that you are not loading the interactive shell startup scripts (the ones ending with rc) from .profile! Otherwise, anytime cd is invoked it will update the recent-directories list, even if it's invoked from non-interactive scripts.

4. Open a new shell session; you can now start using up, z, and h!

Optional Configuration

Details

You can optionally pass additional parameters to fzf:

# OPTIONAL:
#
# Show a nice preview of the directory structure.
# Uses eval to resolve ~.
export COMPNAV_FZF_OPTS="
  --height 80%
  --preview='eval tree -C {} | head -n 50'
  --preview-window=border-double,bottom"
# `z`: Always accept the first match (just an example, personally I don't recommend it).
# export COMPNAV_FZF_Z_OPTS="--select-1 --exit-0 --sync --bind 'start:accept'"

These work in addition to the standard FZF_DEFAULT_OPTS, which is always applied first whenever fzf is invoked.

fzf: find child subdirectory (Alt-C) with bfs

Details

First make sure that you have bfs installed, and consider sponsoring ❤️ them!

Next add this to .bashrc/.zshrc (note that -color requires --ansi in FZF_DEFAULT_OPTS):

export FZF_ALT_C_COMMAND="bfs -color -not -name '.' -nohidden -type d -printf '%P\n' 2>/dev/null"

And optionally consider setting something like this for a nice preview of directories (on Mac, requires installing tree):

# Print tree structure in the preview window
export FZF_ALT_C_OPTS="
  --height 80%
  --preview='tree -C {} | head -n 50'
  --preview-window=border-double,bottom"

Full Example Config

For a full example config, see .zsh-example!

Tests

ruby test/all_tests.rb    # whole suite
ruby test/z_test.rb       # one utility

The tests run the scripts against a throwaway $HOME and a stubbed git, so they never touch your real recent-dirs file and never hit the network. fzf/zsh/bash integration tests skip themselves if the binary is missing.

Improvements over existing tools

Why'd I make this? A few reasons:

• I ran into bugs with the existing tools.
• The existing z works based on "frecency", which offends me on a linguistic and technical level. compnav only considers "recency", which is predictable, more often what you want, and simpler.
• The existing z always jumps to the first result, not giving the user a chance to resolve ambiguity. compnav integrates with fzf in true Unix fashion, allowing a separate tool to do what it does best and take on the job of a selection interface. (If you want the behavior of always accepting the first result, that is also possible with some easy configuration.)
• By integrating with fzf we get fuzzy selection for free, for all the commands.
• compnav's h takes advantage of z's recent-directories index to show projects in recency order.
• The existing tools are mostly written in bash gobbledygook. compnav uses the bare minimum of bash. compnav is written in well-commented Ruby and is easy to read, understand, and modify.

License

The MIT License (MIT)

Copyright (c) 2024 Marcin Swieczkowski