Awesome

[!TIP] Experience Navita, a better choice for directory navigation than SmartCd.

SmartCd

A cd command with improved and extended usability features to quickly navigate your Linux filesystem.

Features • Requirements • Installation • Configurations • Other Info • Known Caveats

Features

• If you're in a git repository and deeply embedded within directories, you can directly traverse to the root of the git repository.

  Synopsis: cd .

• Often when you're deeply embedded within directories, you may want to be able to search and traverse with respect to a particular directory. For example, many users may often feel the need of searching and traversing within their $HOME directory irrespective of what their current working directory is.<br>By default, smartcd will use $HOME as base. User can provide multiple base paths as well (check out SMARTCD_BASE_PATHS & SMARTCD_BASE_DIR_KEYBIND).

  Synopsis: cd (-b | --base) [string ...]

  <img src="https://i.imgur.com/cLaBg3B.gif">

• smartcd can remember the last 50 (default) unique recently visited directory locations, where you can Fuzzy search and automatically traverse to the selected one.

  Synopsis: cd -- [string ...]

  <img src="https://i.imgur.com/UqfGpLw.gif">

• If the provided argument is not in your $CDPATH, then smartcd will present you with a list of all the sub-directories that matched the argument, where you can Fuzzy search & directly traverse to the selected path.

  Synopsis: cd [string ...]

  <img src="https://i.imgur.com/xVDkHD7.gif">

• smartcd can search parent-directories based on the argument string provided. It will list all parent directories that matched the argument string, where you can fuzzy search and automatically traverse to the selected path.

  Synopsis: cd .. [string ...]

  <img src="https://i.imgur.com/rgkVR6v.gif">

• You can pipe options, (with or without) arguments and as well as multiple directory paths stored in a file to smartcd.

  NOTE: Since v3.2.0, you can also use cd with options & arguments along with piping, simultaneously. For example,

   echo ri \!git \'lua | cd -- \'color
   cat $HOME/_testing/rough/dir_paths.txt | cd "bin 'dot"
  

  <img src="https://i.imgur.com/gy3LPnq.gif">

Other Features

• Remove invalid paths from log.

  cd (-c | --clean)
  

• Print version information.

  cd (-v | --version)
  # or
  echo $SMARTCD_VERSION
  

Why SmartCd

Initially, I tried enhancd which is a very good alternative for the inbuilt cd command, but the features of enhancd were more than enough for me and also I had to change my familiarity and regular habit with using some of the default options or arguments that are often used with the inbuilt cd command, just to familiarize and adapt with the tool.

I started by making smartcd remember the last 20 unique visited paths using the -- option. I wanted to keep cd as close to its native implementation, and at the same time increase its usability. The -- option with the cd command was of no particular use to me, so I just provided an extra functionality to that option.

Requirements

• Fzf
• Git

Tested on Zsh & Bash.

Optional requirements but recommended

• Fd
• Ripgrep
• Exa or Tree
  • Fzf will use the current line from the filter as the argument for exa or tree, and will show the result in a split/preview window of the filter.
  • smartcd has inbuilt support for exa and tree, i.e., just install either exa or tree, and smartcd will handle the rest.
  • Otherwise, if you want to use any other tool, you need to export SMARTCD_FZF_PREVIEW_CMD env with your desired command (with options).
  • Even if you want to use exa or tree with different options other than the default ones, you can export SMARTCD_FZF_PREVIEW_CMD env specifying the command with your desired options.

Installation

Manual Installation

1. Clone the repository.

   git clone --depth 1 https://github.com/CodesOfRishi/smartcd.git
   

2. Source the smartcd.sh script in your shell configuration file (.bashrc and/or .zshrc).

   source path/to/smartcd/smartcd.sh
   

   Where path/to/smartcd/smartcd.sh is the path to the smartcd.sh script in the smartcd repository.

3. Open a new shell or reload your shell configuration file.

Zinit

1. Add the below code in your .zshrc (.bashrc).

   zinit ice depth=1
   zinit light "CodesOfRishi/smartcd"
   

2. Open a new shell or reload your shell configuration file.

Sheldon

1. Add the plugin to Sheldon config file.

   sheldon add smartcd --github CodesOfRishi/smartcd
   

2. Open a new shell or reload your shell configuration file.

Configurations

SMARTCD_BASE_PATHS=( 
	"path/to/my/dir1" 
	"path/to/my/proj1" 
	"path/to/my/dir2" 
	"path/to/my/proj2" 
)
export SMARTCD_BASE_PATHS

Other Info

What if the user configures the same options for multiple features?

SmartCd gives priority in the following order:<br>

SMARTCD_HIST_DIR_OPT > SMARTCD_PARENT_DIR_OPT > SMARTCD_LAST_DIR_OPT > SMARTCD_BASE_DIR_OPT > SMARTCD_GIT_ROOT_OPT > SMARTCD_CLEAN_LOG_OPT > SMARTCD_VERSION_OPT

Known Caveats

• cd . won't work if you're in .git/ directory of a git repository.
• cd . will follow up any symbolic links. For e.g., if you're in ~/my-proj/foo/bar and ~/my-proj is symbolic linked to ~/src/my-proj, then cd . command will move you to ~/src/my-proj.
• The piping feature only works with Zsh, because in Bash every command in a pipeline is executed as a separate process (i.e., in a subshell).

Inspiration

enhancd

LICENSE

The MIT License (MIT)

Copyright (c) 2021 Rishi K.