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.
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 ...]
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 ...]
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 ...]
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 ...]
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"
```

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

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

Clone the repository.

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

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.
Open a new shell or reload your shell configuration file.

Zinit

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

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

Open a new shell or reload your shell configuration file.

Sheldon

Add the plugin to Sheldon config file.

sheldon add smartcd --github CodesOfRishi/smartcd

Open a new shell or reload your shell configuration file.

Configurations

SMARTCD_CONFIG_DIR

smartcd stores logs in this location, which defaults to ~/.config/.smartcd. To change location of the log file, export SMARTCD_CONFIG_DIR with your desired location.

SMARTCD_SELECT_ONE

If only 1 matching path is found and if the env is set to

1 then smartcd will directly traverse to the only matched directory path.
0 then smartcd will bring the interactive fzf filter before travering to the path.

This defaults to 0.

SMARTCD_EXACT_SEARCH

Export the env as 1 to perform exact fzf search always. This defaults to 0.

SMARTCD_FZF_PREVIEW_CMD

Command (with options) to use with current line as argument from the fzf filter to show its result in fzf's split/preview window.

For exa, it defaults to exa -TaF -I '.git' --icons --group-directories-first --git-ignore --colour=always.
For tree, it defaults to tree -I '.git' -C -a.

SMARTCD_HIST_DIR_LOG_SIZE

Set number of unique recently visited directory paths smartcd should remember. This defaults to 50.

SMARTCD_COMMAND

To use a custom command name for using smartcd, export SMARTCD_COMMAND env with your desired command name. This defaults to cd.

SMARTCD_FINDER

To manually configure either to use find or fd/fdfind command.

SMARTCD_GREP

To manually configure either to use rg or grep command.

SMARTCD_BASE_PATHS

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.

For e.g., you can configure the array as:

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

It defaults to ( "${HOME}" ).

SMARTCD_BASE_DIR_KEYBIND

User can use CTRL-k (default) keystroke to fuzzy search & select to change the base directory to use (for the current shell) from the SMARTCD_BASE_PATHS array.
This defaults to \\C-k, i.e., CTRL-k

SMARTCD_BASE_DIR_OPT

To use a different option for searching & traversing w.r.t. a particular base directory, export SMARTCD_BASE_DIR_OPT with your desired options with spaces. SmartCd will validate only the first 2 options provided in the env. This defaults to "-b --base".

SMARTCD_PARENT_DIR_OPT

To use a different option name for searching & traversing to parent-directories, export SMARTCD_PARENT_DIR_OPT with your desired option. This defaults to ...

SMARTCD_HIST_DIR_OPT

To use a different option name for searching & traversing to recently visited directories, export SMARTCD_HIST_DIR_OPT with your desired option. This defaults to --.

SMARTCD_LAST_DIR_OPT

To use a different option for traversing to last visited working directory, export SMARTCD_LAST_DIR_OPT with your desired option. This defaults to -.

SMARTCD_GIT_ROOT_OPT

To use a different option name for traversing to root of a git repository, export SMARTCD_GIT_ROOT_OPT with your desired option. This defaults to ..

SMARTCD_CLEAN_LOG_OPT

To use a different option name for removing invalid paths from log, export SMARTCD_CLEAN_LOG_OPT with your desired options with spaces. SmartCd will validate only the first 2 options provided in the env. This defaults to "-c --clean".

SMARTCD_VERSION_OPT

To use a different option name to print version information, export SMARTCD_VERSION_OPT with your desired options with spaces. SmartCd will validate only the first 2 options provided in the env. This defaults to "-v --version".

Other Info

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

SmartCd gives priority in the following order:

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)

CodesOfRishi / smartcd