Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/codesofrishi/smartcd

Expedite your navigation of Linux filesystem.
https://github.com/codesofrishi/smartcd

bash bash-plugin cd cli command-line command-line-tool enhancd fuzzy-search fzf linux shell shell-script smartcd terminal unix zsh zsh-plugin

Last synced: about 1 month ago
JSON representation

Expedite your navigation of Linux filesystem.

Host: GitHub
URL: https://github.com/codesofrishi/smartcd
Owner: CodesOfRishi
License: mit
Created: 2021-11-26T10:49:42.000Z (about 3 years ago)
Default Branch: main
Last Pushed: 2024-09-15T08:24:52.000Z (3 months ago)
Last Synced: 2024-09-15T11:10:34.954Z (3 months ago)
Topics: bash, bash-plugin, cd, cli, command-line, command-line-tool, enhancd, fuzzy-search, fzf, linux, shell, shell-script, smartcd, terminal, unix, zsh, zsh-plugin
Language: Shell
Homepage:
Size: 7.01 MB
Stars: 35
Watchers: 1
Forks: 3
Open Issues: 3
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

> [!TIP]
> Experience [Navita](https://github.com/CodesOfRishi/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](#features) •
[Requirements](#requirements) •
[Installation](#installation) •
[Configurations](#configurations) •
[Other Info](#other-info) •
[Known Caveats](#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,

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

### Other Features
- Remove invalid paths from log.

```bash
cd (-c | --clean)
```

- Print version information.

```bash
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](https://github.com/junegunn/fzf)
- [Git](https://git-scm.com/)

Tested on [Zsh](https://www.zsh.org/) & [Bash](https://www.gnu.org/software/bash/).

### Optional requirements but recommended

- [Fd](https://github.com/sharkdp/fd)
- [Ripgrep](https://github.com/BurntSushi/ripgrep)
- [Exa](https://the.exa.website/) or [Tree](https://linux.die.net/man/1/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.

```bash
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`).

```bash
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](https://github.com/zdharma-continuum/zinit)

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

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

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

### [Sheldon](https://sheldon.cli.rs/)

1. Add the plugin to Sheldon config file.

```bash
sheldon add smartcd --github CodesOfRishi/smartcd
```

2. 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:

```bash
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](https://github.com/b4b4r07/enhancd)

## [LICENSE](https://github.com/CodesOfRishi/smartcd/blob/main/LICENSE)

The MIT License (MIT)