{"id":19819046,"url":"https://github.com/codesofrishi/smartcd","last_synced_at":"2025-05-01T11:32:42.922Z","repository":{"id":45142255,"uuid":"432144435","full_name":"CodesOfRishi/smartcd","owner":"CodesOfRishi","description":"Expedite your navigation of Linux filesystem.","archived":false,"fork":false,"pushed_at":"2024-09-15T08:24:52.000Z","size":7350,"stargazers_count":35,"open_issues_count":3,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-09-15T11:10:34.954Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CodesOfRishi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-11-26T10:49:42.000Z","updated_at":"2024-09-15T08:24:56.000Z","dependencies_parsed_at":"2022-07-21T06:32:36.794Z","dependency_job_id":null,"html_url":"https://github.com/CodesOfRishi/smartcd","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodesOfRishi%2Fsmartcd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodesOfRishi%2Fsmartcd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodesOfRishi%2Fsmartcd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodesOfRishi%2Fsmartcd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CodesOfRishi","download_url":"https://codeload.github.com/CodesOfRishi/smartcd/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224253270,"owners_count":17280936,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","bash-plugin","cd","cli","command-line","command-line-tool","enhancd","fuzzy-search","fzf","linux","shell","shell-script","smartcd","terminal","unix","zsh","zsh-plugin"],"created_at":"2024-11-12T10:17:39.785Z","updated_at":"2024-11-12T10:17:40.428Z","avatar_url":"https://github.com/CodesOfRishi.png","language":"Shell","readme":"\u003e [!TIP]\n\u003e Experience [Navita](https://github.com/CodesOfRishi/navita), a better choice for directory navigation than SmartCd.\n\n\u003cdiv align=\"center\"\u003e\n\n# SmartCd\n\nA `cd` command with improved and extended usability features to quickly navigate your Linux filesystem.\n\n[Features](#features) •\n[Requirements](#requirements) •\n[Installation](#installation) •\n[Configurations](#configurations) •\n[Other Info](#other-info) •\n[Known Caveats](#known-caveats)\n\n\u003c/div\u003e\n\n## Features\n\n- If you're in a git repository and deeply embedded within directories, you can directly traverse to the root of the git repository.\n\n  **Synopsis:** `cd .`\n\n- 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.\u003cbr\u003eBy default, `smartcd` will use `$HOME` as base. User can provide multiple base paths as well (check out `SMARTCD_BASE_PATHS` \u0026 `SMARTCD_BASE_DIR_KEYBIND`).\n\n  **Synopsis:** `cd (-b | --base) [string ...]`\n\n  \u003cimg src=\"https://i.imgur.com/cLaBg3B.gif\"\u003e\n\n- `smartcd` can remember the last 50 (default) unique recently visited directory locations, where you can Fuzzy search and automatically traverse to the selected one.\n\n  **Synopsis:** `cd -- [string ...]`\n\n  \u003cimg src=\"https://i.imgur.com/UqfGpLw.gif\"\u003e\n\n- 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 \u0026 directly traverse to the selected path.\n\n  **Synopsis:** `cd [string ...]`\n\n  \u003cimg src=\"https://i.imgur.com/xVDkHD7.gif\"\u003e\n\n- `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.\n\n  **Synopsis:** `cd .. [string ...]`\n\n  \u003cimg src=\"https://i.imgur.com/rgkVR6v.gif\"\u003e\n\n- You can pipe options, (with or without) arguments and as well as multiple directory paths stored in a file to `smartcd`.\n\n  **NOTE**: Since v3.2.0, you can also use `cd` with options \u0026 arguments along with piping, simultaneously.\n  For example,\n\n  ```bash\n   echo ri \\!git \\'lua | cd -- \\'color\n   cat $HOME/_testing/rough/dir_paths.txt | cd \"bin 'dot\"\n  ```\n\n  \u003cimg src=\"https://i.imgur.com/gy3LPnq.gif\"\u003e\n\n### Other Features\n- Remove invalid paths from log.\n\n  ```bash\n  cd (-c | --clean)\n  ```\n\n- Print version information.\n\n  ```bash\n  cd (-v | --version)\n  # or\n  echo $SMARTCD_VERSION\n  ```\n\n\n## Why SmartCd\n\nInitially, 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.\n\nI 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.\n\n## Requirements\n\n- [Fzf](https://github.com/junegunn/fzf)\n- [Git](https://git-scm.com/)\n\nTested on [Zsh](https://www.zsh.org/) \u0026 [Bash](https://www.gnu.org/software/bash/).\n\n### Optional requirements but recommended\n\n- [Fd](https://github.com/sharkdp/fd)\n- [Ripgrep](https://github.com/BurntSushi/ripgrep)\n- [Exa](https://the.exa.website/) or [Tree](https://linux.die.net/man/1/tree)\n  - 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.\n  - `smartcd` has inbuilt support for `exa` and `tree`, i.e., just install either `exa` or `tree`, and `smartcd` will handle the rest.\n  - Otherwise, if you want to use any other tool, you need to export `SMARTCD_FZF_PREVIEW_CMD` env with your desired command (with options).\n  - 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.\n\n\n## Installation\n\n### Manual Installation\n\n1. Clone the repository.\n\n   ```bash\n   git clone --depth 1 https://github.com/CodesOfRishi/smartcd.git\n   ```\n   \n2. Source the `smartcd.sh` script in your shell configuration file (`.bashrc` and/or `.zshrc`).\n\n   ```bash\n   source path/to/smartcd/smartcd.sh\n   ```\n\n   Where `path/to/smartcd/smartcd.sh` is the path to the `smartcd.sh` script in the smartcd repository.\n\n3. Open a new shell or reload your shell configuration file.\n\n### [Zinit](https://github.com/zdharma-continuum/zinit)\n\n1. Add the below code in your `.zshrc` (~~`.bashrc`~~).\n\n   ```bash\n   zinit ice depth=1\n   zinit light \"CodesOfRishi/smartcd\"\n   ```\n\n2. Open a new shell or reload your shell configuration file.\n\n### [Sheldon](https://sheldon.cli.rs/)\n\n1. Add the plugin to Sheldon config file.\n\n   ```bash\n   sheldon add smartcd --github CodesOfRishi/smartcd\n   ```\n\n2. Open a new shell or reload your shell configuration file.\n\n## Configurations\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_CONFIG_DIR\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003ccode\u003esmartcd\u003c/code\u003e stores logs in this location, which defaults to \u003ccode\u003e~/.config/.smartcd\u003c/code\u003e. To change location of the log file, export \u003ccode\u003eSMARTCD_CONFIG_DIR\u003c/code\u003e with your desired location.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_SELECT_ONE\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\nIf only 1 matching path is found and if the env is set to\n\u003cul\u003e\n\u003cli\u003e\u003ccode\u003e1\u003c/code\u003e then \u003ccode\u003esmartcd\u003c/code\u003e will directly traverse to the only matched directory path.\u003c/li\u003e\n\u003cli\u003e\u003ccode\u003e0\u003c/code\u003e then \u003ccode\u003esmartcd\u003c/code\u003e will bring the interactive \u003ccode\u003efzf\u003c/code\u003e filter before travering to the path.\u003c/li\u003e\n\u003c/ul\u003e\nThis defaults to \u003ccode\u003e0\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_EXACT_SEARCH\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\nExport the env as \u003ccode\u003e1\u003c/code\u003e to perform exact fzf search always. This defaults to \u003ccode\u003e0\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_FZF_PREVIEW_CMD\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e \nCommand (with options) to use with current line as argument from the \u003ccode\u003efzf\u003c/code\u003e filter to show its result in \u003ccode\u003efzf\u003c/code\u003e's split/preview window.\n\u003cul\u003e\n\u003cli\u003eFor \u003ccode\u003eexa\u003c/code\u003e, it defaults to \u003ccode\u003eexa -TaF -I '.git' --icons --group-directories-first --git-ignore --colour=always\u003c/code\u003e.\u003c/li\u003e\n\u003cli\u003eFor \u003cCode\u003etree\u003c/Code\u003e, it defaults to \u003cCode\u003etree -I '.git' -C -a\u003c/Code\u003e.\u003c/li\u003e\n\u003c/ul\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_HIST_DIR_LOG_SIZE\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e \nSet number of unique recently visited directory paths \u003ccode\u003esmartcd\u003c/code\u003e should remember. This defaults to 50.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_COMMAND\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e \nTo use a custom command name for using smartcd, export \u003ccode\u003eSMARTCD_COMMAND\u003c/code\u003e env with your desired command name. This defaults to \u003ccode\u003ecd\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_FINDER\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e \nTo manually configure either to use \u003ccode\u003efind\u003c/code\u003e or \u003ccode\u003efd\u003c/code\u003e/\u003ccode\u003efdfind\u003c/code\u003e command.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_GREP\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e \nTo manually configure either to use \u003ccode\u003erg\u003c/code\u003e or \u003ccode\u003egrep\u003c/code\u003e command.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_BASE_PATHS\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e \n\u003cul\u003e\n\u003cli\u003eAn array which stores multiple base directory paths. You can add multiple base directory paths to the array \u0026 the 1st element of the array will always be used as base.\u003c/li\u003e\n\u003cli\u003eFor e.g., you can configure the array as:\n\u003cp\u003e\n\n```bash\nSMARTCD_BASE_PATHS=( \n\t\"path/to/my/dir1\" \n\t\"path/to/my/proj1\" \n\t\"path/to/my/dir2\" \n\t\"path/to/my/proj2\" \n)\nexport SMARTCD_BASE_PATHS\n```\n\u003c/p\u003e\n\u003cli\u003eIt defaults to \u003ccode\u003e( \"${HOME}\" )\u003c/code\u003e.\u003c/li\u003e\n\u003c/ul\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_BASE_DIR_KEYBIND\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e \n\u003cul\u003e\n\u003cli\u003eUser can use \u003ccode\u003eCTRL-k\u003c/code\u003e (default) keystroke to fuzzy search \u0026 select to change the base directory to use (for the current shell) from the \u003ccode\u003eSMARTCD_BASE_PATHS\u003c/code\u003e array.\u003c/li\u003e\n\u003cli\u003eThis defaults to \u003ccode\u003e\\\\C-k\u003c/code\u003e, i.e., \u003ccode\u003eCTRL-k\u003c/code\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_BASE_DIR_OPT\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e \nTo use a different option for searching \u0026 traversing w.r.t. a particular base directory, export \u003ccode\u003eSMARTCD_BASE_DIR_OPT\u003c/code\u003e with your desired options with \u003ci\u003espaces\u003c/i\u003e. SmartCd will validate only the first 2 options provided in the env. This defaults to \u003ccode\u003e\"-b --base\"\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_PARENT_DIR_OPT\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e \nTo use a different option name for searching \u0026 traversing to parent-directories, export \u003ccode\u003eSMARTCD_PARENT_DIR_OPT\u003c/code\u003e with your desired option. This defaults to \u003ccode\u003e..\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_HIST_DIR_OPT\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e \nTo use a different option name for searching \u0026 traversing to recently visited directories, export \u003ccode\u003eSMARTCD_HIST_DIR_OPT\u003c/code\u003e with your desired option. This defaults to \u003ccode\u003e--\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_LAST_DIR_OPT\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e \nTo use a different option for traversing to last visited working directory, export \u003ccode\u003eSMARTCD_LAST_DIR_OPT\u003c/code\u003e with your desired option. This defaults to \u003ccode\u003e-\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_GIT_ROOT_OPT\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e \nTo use a different option name for traversing to root of a git repository, export \u003ccode\u003eSMARTCD_GIT_ROOT_OPT\u003c/code\u003e with your desired option. This defaults to \u003ccode\u003e.\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_CLEAN_LOG_OPT\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e \nTo use a different option name for removing invalid paths from log, export \u003ccode\u003eSMARTCD_CLEAN_LOG_OPT\u003c/code\u003e with your desired options with \u003ci\u003espaces\u003c/i\u003e. SmartCd will validate only the first 2 options provided in the env. This defaults to \u003ccode\u003e\"-c --clean\"\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSMARTCD_VERSION_OPT\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e \nTo use a different option name to print version information, export \u003ccode\u003eSMARTCD_VERSION_OPT\u003c/code\u003e with your desired options with \u003ci\u003espaces\u003c/i\u003e. SmartCd will validate only the first 2 options provided in the env. This defaults to \u003ccode\u003e\"-v --version\"\u003c/code\u003e.\n\u003c/details\u003e\n\n## Other Info\n\n**What if the user configures the same options for multiple features?** \n\nSmartCd gives priority in the following order:\u003cbr\u003e\n\n`SMARTCD_HIST_DIR_OPT` \u003e `SMARTCD_PARENT_DIR_OPT` \u003e `SMARTCD_LAST_DIR_OPT` \u003e `SMARTCD_BASE_DIR_OPT` \u003e `SMARTCD_GIT_ROOT_OPT` \u003e `SMARTCD_CLEAN_LOG_OPT` \u003e `SMARTCD_VERSION_OPT` \n\n## Known Caveats\n\n- `cd .` won't work if you're in `.git/` directory of a git repository.\n- `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`.\n- 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).\n\n## Inspiration\n\n[enhancd](https://github.com/b4b4r07/enhancd)\n\n## [LICENSE](https://github.com/CodesOfRishi/smartcd/blob/main/LICENSE)\n\nThe MIT License (MIT)\n\nCopyright (c) 2021 Rishi K.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodesofrishi%2Fsmartcd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodesofrishi%2Fsmartcd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodesofrishi%2Fsmartcd/lists"}