{"id":17920916,"url":"https://github.com/eth-p/fish-plugin-better-cd","last_synced_at":"2025-04-03T08:36:16.009Z","repository":{"id":126317221,"uuid":"375197643","full_name":"eth-p/fish-plugin-better-cd","owner":"eth-p","description":"A better version of cd (and pushd) for your Fish shell.","archived":false,"fork":false,"pushed_at":"2022-04-16T21:40:03.000Z","size":21,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-08T22:13:35.185Z","etag":null,"topics":["fish","fish-plugin","fish-shell","fisher","fisherman","fuzzy-cd","oh-my-fish"],"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/eth-p.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-09T02:05:59.000Z","updated_at":"2023-02-26T20:17:55.000Z","dependencies_parsed_at":"2023-06-16T06:45:40.046Z","dependency_job_id":null,"html_url":"https://github.com/eth-p/fish-plugin-better-cd","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eth-p%2Ffish-plugin-better-cd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eth-p%2Ffish-plugin-better-cd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eth-p%2Ffish-plugin-better-cd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eth-p%2Ffish-plugin-better-cd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eth-p","download_url":"https://codeload.github.com/eth-p/fish-plugin-better-cd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246968802,"owners_count":20862481,"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":["fish","fish-plugin","fish-shell","fisher","fisherman","fuzzy-cd","oh-my-fish"],"created_at":"2024-10-28T20:29:37.276Z","updated_at":"2025-04-03T08:36:15.986Z","avatar_url":"https://github.com/eth-p.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Better `cd` for Fish Shell\n\nA better version of `cd` (and `pushd`) for your Fish shell.\n\n\n## Install\n\nWith [fisher](https://github.com/jorgebucaran/fisher):\n\n```\nfisher add eth-p/fish-plugin-better-cd\n```\n\nYou can also alias `cd` to `bettercd`, if you like:\n\n```fish\nalias cd bettercd\nalias cdun bettercd --undo\n```\n\nIf you're familiar with `fzf` or `z`, there's a couple of recommended defaults:\n\n\u003cdetails\u003e\u003csummary\u003eLike fzf:\u003c/summary\u003e\n\nFuzzily enter part of the path name, and a `fzf` prompt will be displayed if there are multiple matches.\n\n```fish\nset -U bettercd_resolve  fzf\nset -U bettercd_tiebreak common,fzf\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eLike z:\u003c/summary\u003e\n\nFuzzily enter part of the path name, and the common parent or highest weighted candidate will be used.\n\n```fish\nset -U bettercd_resolve  z,fzf\nset -U bettercd_tiebreak common,z\nset -U bettercd_search_z all\n```\n\n\u003c/details\u003e\n\n\n\n## Features\n\n**Change directories with `:/path-relative-to-git-root`.**  \nJust like `git add`, and with completion support.\n\n```fish\n$ git init\n$ mkdir folder\n$ mkdir -p other/folder\n$ bettercd folder \u0026\u0026 pwd\n/repo/folder\n\n$ bettercd :/other/folder \u0026\u0026 pwd\n/repo/other/folder\n```\n\n\n\n**Fuzzy find your directories with `fzf` or `z`**  \n(requires [fzf](https://github.com/junegunn/fzf) and either [fd](https://github.com/sharkdp/fd) or [z](https://github.com/jethrokuan/z); must be enabled, see below)\n\n```console\n$ mkdir -p foo/bar/baz\n$ mkdir -p foo/cat/dog\n$ bettercd baz \u0026\u0026 pwd\n/tmp/foo/bar/baz\n\n$ bettercd ../../dog \u0026\u0026 pwd\n/tmp/foo/cat/dog\n\n$ bettercd proj \u0026\u0026 pwd\n/home/me/projects\n```\n\n\n\n**Undo your previous `bettercd`.**   \nDid you not mean to change to that directory?\n\n```console\n$ pwd\n/home/me/desktop\n\n$ bettercd ~/downloads \u0026\u0026 pwd\n/home/me/downloads\n\n$ bettercd --undo \u0026\u0026 pwd\n/home/me/desktop\n```\n\n\n\n## Configuration\n\nAll configuration is done with variables, preferably with `set -U` for universal variables.\n\n### Features\n\n- `bettercd_resolve` (default: `fzf`, format: `resolver,resolver,...`)  \n  Specifies which [resolvers](#resolvers) are used for populating the list of candidate directories.\n\n- `bettercd_tiebreak` (default: `common,fzf`, format: `tiebreaker,tiebreaker,...`)  \n  Specifies which [tiebreakers](#tiebreakers) are used for picking between multiple candidate directories.\n\n- `bettercd_reporel` (default: `true`, format: `true` or `false`)  \n  If enabled, allows navigating relative to the git repo root with `:/path/from/root`.\n  Fuzzy matching is also still available for this!\n\n### Search Settings\n\n- `bettercd_search_depth` (default: `4`, format: `number`)  \n  Specifies how deep of a search the [fzf resolver](#fzf-resolver) will do.\n\n- `bettercd_search_z` (default: `best`, format: `all`, `best` or `common`)  \n  When using the [z resolver](#z-resolver), what answers returned by `z` will be used.\n\n- `bettercd_user_search_exclude_paths` (format: array)  \n  Speicifes a list of absolute paths that the [fzf resolver](#fzf-resolver) will ignore.\n\n- `bettercd_user_search_exclude_names` (format: array)  \n  Speicifes a list of file globs that the [fzf resolver](#fzf-resolver) will ignore.\n\n### Tweaks\n\n- `bettercd_fzf_args` (format: array)  \n  A list of arguments passed to `fzf` in the [fzf resolver](#fzf-resolver).\n- `bettercd_fzf_interactive_args` (default: something nice, format: array)  \n  A list of arguments passed to `fzf` in the [fzf tiebreaker](#fzf-tiebreaker).\n- `bettercd_fd_args` (format: array)  \n  A list of arguments passed to `fd` in the [fzf resolver](#fzf-resolver).\n\n\n\n## Resolvers\n\nBettercd's fuzzy matching works by collecting a list of candidate paths for the provided search path. This is done with resolver functions, which take the search path and print out a list of candidate paths.\n\n### fzf-resolver\n\n\u003e (requires [fzf](https://github.com/junegunn/fzf) and [fd](https://github.com/sharkdp/fd))\n\nThe `fzf` resolver uses a combination of `fd` and `fzf` to return a list of fuzzily-matching paths under the target directory. It is *very* likely to return a ton of candidates, and it's recommended to use the `fzf` tiebreaker to pick one.\n\n### z-resolver\n\n\u003e (requires [z](https://github.com/jethrokuan/z))\n\nThe `z` resolver uses `z` to print a list of paths that would be matched by `z`.\nYou can configure how many paths are returned by setting `bettercd_search_z` to either `best`, `all`, or `common`.\n\n### Custom Resolvers\n\nYou can create custom resolvers by defining a `__bettercd_resolve_with_RESOLVER` function:\n\n```fish\nfunction __bettercd_resolve_with_homedir\n\tfor dir in $HOME/*\n\t\tprintf \"%s\\n\" -- \"$HOME\"\n\tend\nend\n```\n\n\n\n## Tiebreakers\n\nWhenever bettercd's fuzzy matching returns more than one candidate, it needs to be narrowed down to a single result. For this, there are tiebreaker functions.\n\n### fzf-tiebreaker\n\n\u003e (requires [fzf](https://github.com/junegunn/fzf))\n\nThe `fzf` tiebreaker displays a list of candidates, and asks you to pick one.\n\n### z-tiebreaker\n\n\u003e (requires [z](https://github.com/jethrokuan/z) and perl)\n\nThe `z` tiebreaker uses the `z` database to pick the highest-weighted directory from the list of candidates. If no candidate is located in the database, the next tiebreaker will be used instead.\n\n### common-tiebreaker\n\nThe `common` tiebreaker simply picks the common parent of all candiates, if there is one. This is good for navigating to a parent directory without considering any of its children.\n\n### Custom Tiebreakers\n\nYou can create custom resolvers by defining a `__bettercd_tiebreak_with_TIEBREAKER` function:\n\n```fish\nfunction __bettercd_tiebreak_with_first\n    argparse 'x-nothing' -- $argv || return $status\n\techo $argv[1]\nend\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feth-p%2Ffish-plugin-better-cd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feth-p%2Ffish-plugin-better-cd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feth-p%2Ffish-plugin-better-cd/lists"}