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.

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

You will need:

1. fzf (it's great, please consider sponsoring ❤️ them!)
2. Ruby (hopefully old versions work, though I haven't tested it).

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:
#
# 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'"

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

# 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"

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

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.

The MIT License (MIT)

Copyright (c) 2024 Marcin Swieczkowski