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

<div align="center">

SmartCd

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

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

</div>

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

<details> <summary><strong><code>SMARTCD_CONFIG_DIR</code></strong></summary> <code>smartcd</code> stores logs in this location, which defaults to <code>~/.config/.smartcd</code>. To change location of the log file, export <code>SMARTCD_CONFIG_DIR</code> with your desired location. </details> <details> <summary><strong><code>SMARTCD_SELECT_ONE</code></strong></summary> If only 1 matching path is found and if the env is set to <ul> <li><code>1</code> then <code>smartcd</code> will directly traverse to the only matched directory path.</li> <li><code>0</code> then <code>smartcd</code> will bring the interactive <code>fzf</code> filter before travering to the path.</li> </ul> This defaults to <code>0</code>. </details> <details> <summary><strong><code>SMARTCD_EXACT_SEARCH</code></strong></summary> Export the env as <code>1</code> to perform exact fzf search always. This defaults to <code>0</code>. </details> <details> <summary><strong><code>SMARTCD_FZF_PREVIEW_CMD</code></strong></summary> Command (with options) to use with current line as argument from the <code>fzf</code> filter to show its result in <code>fzf</code>'s split/preview window. <ul> <li>For <code>exa</code>, it defaults to <code>exa -TaF -I '.git' --icons --group-directories-first --git-ignore --colour=always</code>.</li> <li>For <Code>tree</Code>, it defaults to <Code>tree -I '.git' -C -a</Code>.</li> </ul> </details> <details> <summary><strong><code>SMARTCD_HIST_DIR_LOG_SIZE</code></strong></summary> Set number of unique recently visited directory paths <code>smartcd</code> should remember. This defaults to 50. </details> <details> <summary><strong><code>SMARTCD_COMMAND</code></strong></summary> To use a custom command name for using smartcd, export <code>SMARTCD_COMMAND</code> env with your desired command name. This defaults to <code>cd</code>. </details> <details> <summary><strong><code>SMARTCD_FINDER</code></strong></summary> To manually configure either to use <code>find</code> or <code>fd</code>/<code>fdfind</code> command. </details> <details> <summary><strong><code>SMARTCD_GREP</code></strong></summary> To manually configure either to use <code>rg</code> or <code>grep</code> command. </details> <details> <summary><strong><code>SMARTCD_BASE_PATHS</code></strong></summary> <ul> <li>An array which stores multiple base directory paths. You can add multiple base directory paths to the array & the 1st element of the array will always be used as base.</li> <li>For e.g., you can configure the array as: <p>

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

</p> <li>It defaults to <code>( "${HOME}" )</code>.</li> </ul> </details> <details> <summary><strong><code>SMARTCD_BASE_DIR_KEYBIND</code></strong></summary> <ul> <li>User can use <code>CTRL-k</code> (default) keystroke to fuzzy search & select to change the base directory to use (for the current shell) from the <code>SMARTCD_BASE_PATHS</code> array.</li> <li>This defaults to <code>\\C-k</code>, i.e., <code>CTRL-k</code></li> </ul> </details> <details> <summary><strong><code>SMARTCD_BASE_DIR_OPT</code></strong></summary> To use a different option for searching & traversing w.r.t. a particular base directory, export <code>SMARTCD_BASE_DIR_OPT</code> with your desired options with <i>spaces</i>. SmartCd will validate only the first 2 options provided in the env. This defaults to <code>"-b --base"</code>. </details> <details> <summary><strong><code>SMARTCD_PARENT_DIR_OPT</code></strong></summary> To use a different option name for searching & traversing to parent-directories, export <code>SMARTCD_PARENT_DIR_OPT</code> with your desired option. This defaults to <code>..</code>. </details> <details> <summary><strong><code>SMARTCD_HIST_DIR_OPT</code></strong></summary> To use a different option name for searching & traversing to recently visited directories, export <code>SMARTCD_HIST_DIR_OPT</code> with your desired option. This defaults to <code>--</code>. </details> <details> <summary><strong><code>SMARTCD_LAST_DIR_OPT</code></strong></summary> To use a different option for traversing to last visited working directory, export <code>SMARTCD_LAST_DIR_OPT</code> with your desired option. This defaults to <code>-</code>. </details> <details> <summary><strong><code>SMARTCD_GIT_ROOT_OPT</code></strong></summary> To use a different option name for traversing to root of a git repository, export <code>SMARTCD_GIT_ROOT_OPT</code> with your desired option. This defaults to <code>.</code>. </details> <details> <summary><strong><code>SMARTCD_CLEAN_LOG_OP