Enhancd
:rocket: A next-generation cd command with your interactive filter
Install / Use
/learn @babarot/EnhancdREADME
enhan/cd
enhancd is an enhanced cd command integrated with a command line fuzzy finder based on UNIX concept.
Typing “cd” in your console, enhancd provides you a new window to visit a directory. The basic UX of enhancd is almost same as builtin cd command but totally differenent in that you can choose where to go from the list of visited directories in the past. You can select the directory you want to visit using your favorite command line interactive filter (e.g. fzf). It just extends original cd command but brings you completely new experience.
</div> <!-- Naming: - enhan/cd - enhanc<sup>e</sup>d - enhan<sup>/</sup>cd Features: - Go to the visited directory in the past - Easy to filter, using your favorite filter - Work on Bash, Zsh and fish (cross-shell compatibility) - Go back to a specific parent directory like [zsh-bd](https://github.com/Tarrasch/zsh-bd) - Inside a git repo, the first list element is the git root directory - Fuzzy search in a similar name directory - Support standard input (`echo $HOME | cd` is acceptable) - Custom options (user-defined option is acceptable) --> <!-- vim-markdown-toc GFM --> <!-- vim-markdown-toc -->Getting Started
<picture> <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/4442708/229307417-50cf53de-594f-4a19-8547-9820d3af2f1c.gif"> <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/4442708/229307415-32cb36ee-491d-47c5-b852-e94d802e9584.gif"> <img alt="demo" src="https://user-images.githubusercontent.com/4442708/229307417-50cf53de-594f-4a19-8547-9820d3af2f1c.gif"> </picture>Trying enhancd on the current shell, you need to run this command:
source ./init.sh
After that, cd is aliased to __enhancd::cd so you can use enhancd feature by typing cd as usual.
Using enhancd feature requires a command line fuzzy finder tool (as known as an interactive filter), for example, fzf. The ENHANCD_FILTER is the command name for interactive filters. It is a colon-separated list of executables. Each arguments can be also included to the list. It searches from the top of the list and uses the first installed one. A default value is fzy:fzf:peco:sk:zf.
Changing the order of each executables in the list, you can change the interactive filter command used by enhancd. Let’s configure what’s your favorite one!
$ export ENHANCD_FILTER="fzf --height 40%:fzy"
Usage
The usage of cd command powered by enhancd is almost same as built-in cd command.
$ cd [-|..|.] <dir>
Argument | Behavior
---|---
(none) | List all directories visited in the past. The HOME is always shown at a top of the list as builtin cd does. <br> <img width="600" alt="" src="https://user-images.githubusercontent.com/4442708/229298754-9dcd8e18-5777-4b23-bdcf-1aa4e06ac92b.png">
<dir> (exists in cwd) | Go to dir without the filter command (same as builtin cd) <br> <img width="600" alt="" src="https://user-images.githubusercontent.com/4442708/229298751-ed509919-4ebc-4b59-90d9-bb7792aa9fd0.png">
<dir> (not exists in cwd) | Find directories matched with dir or being similar to dir and then pass them to the filter command. A directory named "afx" is not in the current directory but enhancd cd can show where to go from the visited log. <br> <img width="600" alt="" src="https://user-images.githubusercontent.com/4442708/229298749-ec8c0bca-100f-4b8a-9d21-510ce1666831.png">
- | List latest 10 directories <br> <img width="600" alt="" src="https://user-images.githubusercontent.com/4442708/229298748-ad6380ff-4498-4b30-9f8a-46b792ca4669.png">
.. | List all parent directories of cwd <br> <img width="600" alt="" src="https://user-images.githubusercontent.com/4442708/229298747-039a2d06-2e1a-4b27-b009-e78a9c74c6ea.png">
. | List all sub directories in cwd <br> <img width="600" alt="" src="https://user-images.githubusercontent.com/4442708/229298744-b6f8cab1-654b-4197-855b-9f1d84c4c933.png">
Hyphen (-)
List latest 10 directories. This is useful for choosing the directory recently visited only. The number of directories shown as the choices can be changed as you like by editing ENHANCD_HYPHEN_NUM (Defaults to 10).
$ cd -
❯ enhancd
2/10
> /Users/babarot/src/github.com/babarot/enhancd
/Users/babarot/src/github.com/babarot/enhancd/src
To disable this feature, set ENHANCD_ENABLE_HYPHEN to false.
Double-dot (..)
List all parent directories of the current working directory to quickly go back to any directory instead of typing cd ../../.. redundantly.
Let's say you're in ~/src/github.com/babarot/enhancd. The result of cd .. will be:
$ cd ..
❯ _
6/6
> /Users/babarot/src/github.com/babarot
/Users/babarot/src/github.com
/Users/babarot/src
/Users/babarot
/Users
/
To disable this feature, set ENHANCD_ENABLE_DOUBLE_DOT to false.
Single-dot (.)
List all sub directories recursively located under the current directory. The built-in cd command does nothing even if a dot (.) is passed. Whereas, in enhancd cd, it's useful for visiting any sub directory easily (the example below is that if you're in "enhancd" directory):
$ cd .
❯ _
8/8
> .github/
.github/ISSUE_TEMPLATE/
.github/workflows/
conf.d/
functions/
functions/enhancd/
functions/enhancd/lib/
src/
This would be very useful to find a directory you want to visit within current directory. It uses find command internally to list directories but it would be good to install fd (sharkdp/fd) command. It'll be more fast and also be included hidden directories into the list if fd is used.
To disable this feature, set ENHANCD_ENABLE_SINGLE_DOT to false.
Piping
:bulb: Zsh only.
enhancd allows you to pass one or multiple directory paths to cd commands like this:
$ (paths) | cd
Options
$ cd --help
Usage: cd [OPTIONS] [dir]
OPTIONS:
-h, --help Show help message
-q (default) quiet, no output or use of hooks
-s (default) refuse to use paths with symlinks
-L (default) retain symbolic links ignoring CHASE_LINKS
-P (default) resolve symbolic links as CHASE_LINKS
Version: 2.3.0
In enhancd, all options are defined at a configuration file (config.ltsv). This mechanism allows you to add what you want as new option or delete unneeded default options. It uses LTSV (Labeled Tab-Separated Values) format.
For example, let's say you want to use ghq list as custom inputs for cd command. In this case, all you have to do is just to add this one line to your any config.ltsv:
short:-G long:--ghq desc:Show ghq path func:ghq list --full-path condition:which ghq
Label | Description
---|---
short (*) | a short option (e.g. -G)
long (*) | a long option (e.g. --ghq)
desc | a description for the option
func (*) | a command which returns directory list (e.g. ghq list --full-path)
condition | a command which determine that the option should be implemented or not (e.g. which ghq)
format | a string which indicates how to format a line selected by the filter before passing cd command. % is replaced as a selected line and then passed to cd command (e.g. $HOME/src/%). This is useful for the case that input sources for the interactive filter are not a full-path.
<!-- <img width="600" alt="" src="https://user-images.githubusercontent.com/4442708/229298741-236f2920-cde2-4184-9fd3-72849af7a223.png"> --> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/4442708/229365175-aecfe844-cbd7-4ee2-87a6-ea8471ac9b6f.gif"> <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/4442708/229365177-6c8d6056-9ba3-4f22-ba28-48f3991f9f98.gif"> <img alt="options" src="https://user-images.githubusercontent.Note:
*: A required key. But eithershortorlongis good enough.
