{"id":13395237,"url":"https://github.com/bigH/git-fuzzy","last_synced_at":"2025-03-13T20:31:58.795Z","repository":{"id":37473243,"uuid":"262982996","full_name":"bigH/git-fuzzy","owner":"bigH","description":"interactive `git` with the help of `fzf`","archived":false,"fork":false,"pushed_at":"2024-09-21T07:04:03.000Z","size":14020,"stargazers_count":2323,"open_issues_count":2,"forks_count":43,"subscribers_count":18,"default_branch":"main","last_synced_at":"2024-10-29T15:33:54.599Z","etag":null,"topics":[],"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/bigH.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":"2020-05-11T08:25:10.000Z","updated_at":"2024-10-26T21:43:23.000Z","dependencies_parsed_at":"2024-10-25T15:08:12.330Z","dependency_job_id":null,"html_url":"https://github.com/bigH/git-fuzzy","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/bigH%2Fgit-fuzzy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigH%2Fgit-fuzzy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigH%2Fgit-fuzzy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigH%2Fgit-fuzzy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bigH","download_url":"https://codeload.github.com/bigH/git-fuzzy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243456501,"owners_count":20293896,"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":[],"created_at":"2024-07-30T17:01:47.142Z","updated_at":"2025-03-13T20:31:58.773Z","avatar_url":"https://github.com/bigH.png","language":"Shell","readme":"# `git-fuzzy`\n\nA CLI interface to git that relies heavily on [`fzf`](https://github.com/junegunn/fzf) (version `0.21.0` or higher).\n\nYou can run `git add` and `git reset` by selecting or cursoring. You can commit interactively.\n\n![status manager](gifs/status.gif)\n\nYou can search the diff from the query bar and the RHS diff will be highlighted accordingly.\n\n![diff viewer](gifs/diff.gif)\n\nSearch the log and corresponding diff at once. Notice that when you use `|` the left hand side is sent to `log` while the right hand side is sent to `diff`.\n\n![log viewer](gifs/log.gif)\n\n## Installing\n\n`fzf` is **required**:\n```bash\nbrew install fzf\n```\n\n### Bash\n```bash\ngit clone https://github.com/bigH/git-fuzzy.git\n\n# add the executable to your path\necho \"export PATH=\\\"$(pwd)/git-fuzzy/bin:\\$PATH\\\"\" \u003e\u003e ~/.bashrc\n```\n\n### Zsh\n```bash\ngit clone https://github.com/bigH/git-fuzzy.git\n\n# add the executable to your path\necho \"export PATH=\\\"$(pwd)/git-fuzzy/bin:\\$PATH\\\"\" \u003e\u003e ~/.zshrc\n```\n\nAlternatively, you can use a plugin manager:\n\n#### Antibody\nUpdate your `.zshrc` file with the following line:\n```\nantibody bundle bigH/git-fuzzy path:bin kind:path\n```\n\n#### Znap\nRun the following on the command line:\n```\nznap install bigH/git-fuzzy\n```\n\n#### zplug\n```\nzplug \"bigH/git-fuzzy\", as:command, use:\"bin/git-fuzzy\"\n```\n\n#### zinit\n```\nzinit ice as\"program\" pick\"bin/git-fuzzy\"\nzinit light bigH/git-fuzzy\n```\n\n### Fish\n```\ngit clone https://github.com/bigH/git-fuzzy.git\n\n# add the executable to your path\necho \"set -x PATH (pwd)\\\"/git-fuzzy/bin:\\$PATH\\\"\" \u003e\u003e ~/.config/fish/config.fish\n```\n\n## Usage\n\nSimply install and run `git fuzzy` and you can begin using the menu.\n\n**Supported sub-commands**:\n\n- `git fuzzy status` (or `git fuzzy` -\u003e `status`)\n\n    Interact with staged and unstaged changes.\n\n- `git fuzzy branch` (or `git fuzzy` -\u003e `branch`)\n\n    Search for, checkout and look at branches.\n\n- `git fuzzy log` (or `git fuzzy` -\u003e `log`)\n\n    Look for commits in `git log`. Typing in the search simply filters in the usual `fzf` style.\n\n- `git fuzzy reflog` (or `git fuzzy` -\u003e `reflog`)\n\n    Look for entries in `git reflog`. Typing in the search simply filters in the usual `fzf` style.\n\n- `git fuzzy stash` (or `git fuzzy` -\u003e `stash`)\n\n    Look for entries in `git stash`. Typing in the search simply filters in the usual `fzf` style.\n\n- `git fuzzy diff` (or `git fuzzy` -\u003e `diff`)\n\n    Interactively select diff subjects. Drilling down enables searching through diff contents in a diff browser.\n\n- `git fuzzy pr` (or `git fuzzy` -\u003e `pr`)\n\n    Interactively select and open/diff GitHub pull requests.\n\n## Useful Information\n\nAll items from the menu can be accessed via the CLI by running `git fuzzy \u003ccommand\u003e`. Many of the commands simply pass on additional CLI args to the underlying commands. (e.g. `git fuzzy diff a b -- XYZ` uses the args you provided in the listing and preview)\n\nAny time `git` command output is used in preview or listing, there is a header with the command run (useful for copy-pasting or just knowing what's happening). You can optionally [enable debugging switches](#stability--hacking) to see other commands being run in the background or how commands are routed.\n\n## Customizing\n\nFor the ideal experience, install the following optional tools to your `PATH`:\n\n- [`delta`](https://github.com/dandavison/delta) or [`diff-so-fancy`](https://github.com/so-fancy/diff-so-fancy) for nicer looking diffs\n- [`bat`](https://github.com/sharkdp/bat) for a colorized alternative to `cat`\n- [`eza`](https://github.com/eza-community/eza) for a `git`-enabled, and better colorized alternative to `ls`\n\n`git fuzzy diff` uses `grep` to highlight your search term. The default may clash with `diff` formatting or just not be to your liking. You can configure `git fuzzy` without affecting the global setting.\n\n```bash\nexport GF_GREP_COLOR='1;30;48;5;15'\n```\n\nIf provided, `GF_PREFERRED_PAGER` is used as a way to decorate diffs. Otherwise, `diff-so-fancy`, then `delta` are tried before using raw diffs. **Remember to adequately quote this value as it's subject to string splitting.**\n\n```bash\nexport GF_PREFERRED_PAGER=\"delta --theme=gruvbox --highlight-removed -w __WIDTH__\"\n```\n\nIf present, `bat` is used for highlighting. You can choose different defaults in `git fuzzy` if you so desire.\n\n```bash\n# set them for `git fuzzy` only\nexport GF_BAT_STYLE=changes\nexport GF_BAT_THEME=zenburn\n\n# OR set these globally for all `bat` instances\nexport BAT_STYLE=changes\nexport BAT_THEME=zenburn\n```\n\nYou may often want to use a different branch and remote to use as your \"merge-base\" in `git fuzzy`. _The default is `origin/main`._\n\n```bash\nexport GF_BASE_REMOTE=upstream\nexport GF_BASE_BRANCH=trunk\n```\n\n**FOOTGUN**: If you work in a repository that's changed it's default `HEAD` (e.g. from `master` to `main`) since your initial `clone`, you may need to run `git remote set-head \u003cremote name\u003e \u003cbranch name\u003e`. Use `git symbolic-ref -q \"refs/remotes/\u003cremote name\u003e/HEAD\"` to check what the current value is.\n\nFor some repos, it can be useful to turn off the remote branch listing in `git fuzzy branch`. _By default, `git fuzzy` displays remote branches._\n\n```bash\n# any non-empty value will result in skipping remotes (including 'no')\nexport GF_BRANCH_SKIP_REMOTE_BRANCHES=\"yes\"\n```\n\nYou may want the diff search to behave differently in `git fuzzy diff` (this doesn't apply to `log` or any other command that uses `diff`). The query will be quoted by `fzf` and provided as the next argument. In the default case, that means `-G \u003cquery\u003e`. _The default is `-G`._\n\n```bash\nexport GF_DIFF_SEARCH_DEFAULTS=\"--pickaxe-regex -S\"\n```\n\nYou may want custom formats for your `log` and/or `reflog` experience. This is hidden from the command headers to save room and enable freedom in formatting parameters. **Remember to adequately quote this value as it's subject to string splitting.** If you have trouble quoting formats, you can use a pretty format alias (see `man git-config`) _The default is `--pretty=oneline --abbrev-commit`._\n\n```bash\n# for `git fuzzy log`\nexport GF_LOG_MENU_PARAMS='--pretty=\"%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)\u003c%an\u003e%Creset\" --topo-order'\n\n# for `git fuzzy reflog`\nexport GF_REFLOG_MENU_PARAMS='--pretty=fuzzyformat'\n```\n\nYou can also configure various `git` commands' default args in various contexts. This is hidden from the command headers to save room and enable freedom in formatting parameters. **Remember to adequately quote this value as it's subject to string splitting.** _These are not set by default._\n\n```bash\n# when diffing with branches or commits for preview\nexport GF_DIFF_COMMIT_PREVIEW_DEFAULTS=\"--patch-with-stat\"\n\n# when diffing with branches or commits for preview\nexport GF_DIFF_COMMIT_RANGE_PREVIEW_DEFAULTS=\"--summary\"\n\n# when diffing individual files\nexport GF_DIFF_FILE_PREVIEW_DEFAULTS=\"--indent-heuristic\"\n```\n\nIf you use vertical terminals/windows often, you may want to configure the threshold for switching to a vertical view. This ratio is calculated by running `\"__WIDTH__ / __HEIGHT__ \u003e $GF_VERTICAL_THRESHOLD\"`. This is calculated using GNU `bc`. _The default is `2.0`._\n\n```bash\nexport GF_VERTICAL_THRESHOLD=\"1.7 * __HEIGHT__ / 80\"\n```\n\nYou can also configure how the size of the preview window is calculated. They're calculated using GNU `bc`. Try using [Desmos](https://www.desmos.com/calculator) to tweak the calculation. _The defaults are more complex than shown below._\n\n```bash\n# use __WIDTH__ for horizontal scenarios\nexport GF_HORIZONTAL_PREVIEW_PERCENT_CALCULATION='max(50, min(80, 100 - (7000 / __WIDTH__)))'\n\n# use __HEIGHT__ for horizontal scenarios\nexport GF_VERTICAL_PREVIEW_PERCENT_CALCULATION='max(50, min(80, 100 - (5000 / __HEIGHT__)))'\n```\n\nIn cases where you are using a particularly small terminal, you can configure the following calculations to determine when to hide extraneous things. Note that both defaults use `__HEIGHT__`, but `__WIDTH__` is also available.\n\n```bash\n# use __HEIGHT__ for horizontal scenarios\nexport GF_HORIZONTAL_SMALL_SCREEN_CALCULATION='__HEIGHT__ \u003c= 30'\n\n# use __HEIGHT__ for horizontal scenarios\nexport GF_VERTICAL_SMALL_SCREEN_CALCULATION='__HEIGHT__ \u003c= 60'\n```\n\nYou may want to customize the default keyboard shortcuts. There are [many configuration options available](https://github.com/bigH/git-fuzzy/pull/16/files). Here's an example:\n\n```bash\nexport GIT_FUZZY_STATUS_ADD_KEY='Ctrl-A'\n```\n\nIf you are using nano as your default editor, you need to pass `/dev/tty` as stdin otherwise you may receive an error similar to `Too many errors from stdintor to close the file...`:\n\n```bash\ngit config --global core.editor 'nano \u003c /dev/tty'\n```\n\n`git fuzzy` appends a static list of defaults to your `FZF_DEFAULT_OPTIONS`. If you want to use your own set of `git fuzzy`-specific fzf defaults, you can set `GIT_FUZZY_FZF_DEFAULT_OPTS` which will be used in place. Note that `FZF_DEFAULT_OPTS` is merged with this variable.\n\n## Backups\n\n`git fuzzy` takes a backup of your current sha, branch, index diff, unstaged diff and new files. This is helpful in case you take an action hastily (like discarding a file you meant to stage) or there is a bug. If you'd like snapshots, simply set the variable below. I have the following entry in my `.zshrc` (with corresponding `.gitignore_global`):\n\n```bash\nexport GF_SNAPSHOT_DIRECTORY='.git-fuzzy-snapshots'\n```\n\nAlternatively, if you'd like to avoid having these files in your repo directory, you can simply set the snapshot location like so:\n\n```bash\nexport GF_SNAPSHOT_DIRECTORY=\"$HOME/.git-fuzzy-snapshots\"\n```\n\n## `bc` Usage\n\n`bc` programs are all run with some useful functions defined (`min` and `max`). If you'd like to add any others, you can do so. _This is not set by default._\n\n```bash\n# defining your own function:\nexport GF_BC_LIB='my_favorite_variable = 3.14159;'\n```\n\n## Project-Specific Settings\n\n`git fuzzy` sources `./git-fuzzy-config` if it's present. You can add the following to your `~/.gitignore_global` to avoid having to worry about `git` picking it up:\n\n```gitignore\n.git-fuzzy-config\n```\n\nThis file is sourced at the end, so you can build on top of existing or default configurations:\n\n```bash\n# make the preview bigger, but keep the flexibility\nexport GF_HORIZONTAL_PREVIEW_PERCENT_CALCULATION='(80 + $GF_HORIZONTAL_PREVIEW_PERCENT_CALCULATION) / 2'\n```\n\n## Questions\n\n**Why does the UI flash?**\n\n`execute` from the `fzf` man page states that `fzf` switches to the alternate screen when executing a command. I've filed [this issue](https://github.com/junegunn/fzf/issues/2028), which should enable making the transitions smoother.\n\n## Stability \u0026 Hacking\n\nI built this for myself and it's working reasonably well.\n\nThat being said, I've gone through great pains to polish existing functionality to work pretty nicely. I've made it easy to develop or change features by using debug output to check behavior. All debug output goes to `/dev/stderr`, so you can hack on this while using it in pipes and in your `zsh` or `bash` readline shortcuts.\n\n**These variables are considered `true` if they are non-empty.**\n\n```bash\n# debugging information\nexport GF_DEBUG_MODE=\"YES\"\n\n# commands run by the program (those without headers)\nexport GF_COMMAND_DEBUG_MODE=\"YES\"\n\n# fzf commands run by the program\nexport GF_COMMAND_FZF_DEBUG_MODE=\"YES\"\n\n# log output of commands run by `git fuzzy`\nexport GF_COMMAND_LOG_OUTPUT=\"YES\"\n\n# log internal commands (pretty noisy)\nexport GF_INTERNAL_COMMAND_DEBUG_MODE=\"YES\"\n```\n\nOr, log everything:\n\n```\nGF_DEBUG_MODE=\"YES\" GF_COMMAND_DEBUG_MODE=\"YES\" GF_COMMAND_FZF_DEBUG_MODE=\"YES\" GF_COMMAND_LOG_OUTPUT=\"YES\" GF_INTERNAL_COMMAND_DEBUG_MODE=\"YES\" git fuzzy\n```\n","funding_links":[],"categories":["Shell","Plugins","(Bonus) List all awesome-fzf functions","Development Environment","Git / Github","others","\u003ca name=\"git\"\u003e\u003c/a\u003eGit and accessories"],"sub_categories":["ZSH on Windows","Version Control","Command Line"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FbigH%2Fgit-fuzzy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FbigH%2Fgit-fuzzy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FbigH%2Fgit-fuzzy/lists"}