smartcd

smartcd - A mnemonist cd command with autoexec feature

                          _          _
 ___ _ __ ___   __ _ _ __| |_ ___ __| |
/ __| '_ ` _ \ / _` | '__| __/ __/ _` |
\__ \ | | | | | (_| | |  | || (_| (_| |
|___/_| |_| |_|\__,_|_|   \__\___\__,_|

Description

A cd command with improved usability features, which can remember your recently visited directory paths, search and directly traverse to sub-directories, all with fuzzy searching.

Usage

This tool saves the last visited and valid directories in ~/.config/smartcd/path_history.db. If cd -- is called, smartcd will provide an interative search in ~/.config/smartcd/path_history.db. If exa or tree (both optional) are available, they will be used as a side panel presenting a preview of the selected directory.

If cd is called with partial (case insensitive) folder name, smartcd will try the best options in filesystem and in the database file. For faster search on filesystem, fd will be used, fallbacking to find if fd is not installed.

Besides of helping navigating paths, smartcd comes bundled with an additional feature. If exists a file called .on_entry.smartcd.sh or .on_leave.smartcd.sh, they will be executed at entering (source .on_entry.smartcd.sh) or leaving (source .on_leave.smartcd.sh) the given folder. For example in a python project folder, create the files as below:

# on entry
echo "source .venv/bin/activate" > .on_entry.smartcd.sh
smarcd --autoexec=".on_entry.smartcd.sh"

# on leave
echo "deactivate" > .on_leave.smartcd.sh
smarcd --autoexec=".on_leave.smartcd.sh"

And smartcd will activate and deactivate the virtual environment as soon as it enters or leaves the project folder.

To avoid potential security breachs, autoexecution must be granted with smartcd --autoexec="[FILE]". If file was changed after this command, it must be executed again, otherwise, file will not be executed due to different checksum. To stop autoexecution, just remove the file or rename it.

It is also possible to define and allow global on_entry and on_leave files. They will be executed only if no custom files are registred in the given folder. Please, notice that those global files doesn't starts with "." (dot).

# on entry
echo "ls -l" > "${SMARTCD_CONFIG_FOLDER}/on_entry.smartcd.sh"
smarcd --autoexec="${SMARTCD_CONFIG_FOLDER}/on_entry.smartcd.sh"

# on leave
echo "echo \"Bye, bye\"" > "${SMARTCD_CONFIG_FOLDER}/on_leave.smartcd.sh"
smarcd --autoexec="${SMARTCD_CONFIG_FOLDER}/on_leave.smartcd.sh"

Shortcuts

Command cd -- is mapped to CTRL + g in BASH and ZSH. Also, the following alias are defined:

-     # return to previous folder, like "cd -"
cd..  # cd ..
..    # cd ..
..2   # cd ../..
..3   # cd ../../..

Installation

Bash and Zsh

1. Get it:

Download the file named smartcd.sh.

curl -O https://raw.githubusercontent.com/lfromanini/smartcd/main/smartcd.sh

2. Include it:

Then source the file in your ~/.bashrc and/or ~/.zshrc:

$EDITOR ~/.bashrc
# and/or
$EDITOR ~/.zshrc

( ... )
+ source path/to/smartcd.sh
( ... )

Finally, reload your configurations.

source ~/.bashrc
# or
source ~/.zshrc

3. Navigate to some paths and don't forget to try cd --!

4. Done! And remember: you can upgrade smartcd with smartcd --upgrade.

Configuration

A directory record will be saved by default at ~/.config/smartcd/path_history.db. This can be overwritten defining SMARTCD_CONFIG_FOLDER and SMARTCD_HIST_FILE variables before sourcing the code. Additionally, it's possible to define the maximum entries remembered overwriting SMARTCD_HIST_SIZE. Initially, this value is set to 100. Autoexec database record will be saved in SMARTCD_CONFIG_FOLDER.

( ... )
SMARTCD_CONFIG_FOLDER="$HOME/myConfigFolder"
SMARTCD_HIST_FILE="myConfigFile.db"
SMARTCD_HIST_SIZE="200"
SMARTCD_AUTOEXEC_FILE="myAutoexec.db"

source path/to/smartcd.sh
( ... )

Starting on version 2.4.0, smartcd now can have an ignore list. It's stored as pipe delimited list in variable SMARTCD_HIST_IGNORE. It also can be customized executing, before sourcing the code:

( ... )
SMARTCD_HIST_IGNORE=".git|.idea|node_modules|__pycache__"

source path/to/smartcd.sh
( ... )

By default, only .git folder is in ignore list. Don't add any / or regex to this variable.

Folders $HOME and / are never stored in database, since they can be reached very easily.

Maintenance

List database file contents and ignore list:

smartcd --list

Remove all invalid paths from database file (for the case when directory doesn't exists anymore) as also cleanups autoexec database:

smartcd --cleanup

Use default $EDITOR to manully edit paths database file (for the case when you want to remove a given path from it):

smartcd --edit

Be careful! This command removes all saved paths and autoexec granted files:

smartcd --reset

Starting on version 2.3.0, smartcd can upgrade itself:

smartcd --upgrade

Other valid entries are --version and --help.

Requirements

• fzf
• md5sum
• A not so old Linux distribuition. Since 2.6 Linux kernel builds have started to offer /dev/shm/ as shared memory in the form of a ramdisk. This /dev/shm/ is used by smartcd for an even better performance.

Optional Requirements

• exa : Directory preview. The icon characters must be present in the font you are using in your terminal - it is the font that contains the icons. The majority of fonts probably not include these glyphs by default. A good solution to this problem is the Nerd Fonts project, which patches existing fixed-width fonts with the necessary icons.
• tree : Directory preview, in case exa is not installed.
• fd : find alternative to search entries in filesystem.

LICENSE

The MIT License (MIT)