💤 forgit
Utility tool for using git interactively. Powered by junegunn/fzf.
This tool is designed to help you use git more efficiently.
It's **lightweight** and **easy to use**.
# 📥 Installation
## Requirements
- [`fzf`](https://github.com/junegunn/fzf) version `0.49.0` or higher
If your OS package manager bundles an older version of `fzf`, you might install it using [`fzf`'s own install script](https://github.com/junegunn/fzf?tab=readme-ov-file#using-git).
## Shell package managers
``` zsh
# for zplug
zplug 'wfxr/forgit'
# for zgen
zgen load 'wfxr/forgit'
# for antigen
antigen bundle 'wfxr/forgit'
# for fisher (requires fisher v4.4.3 or higher)
fisher install wfxr/forgit
# for omf
omf install https://github.com/wfxr/forgit
# for zinit
zinit load wfxr/forgit
# for oh-my-zsh
git clone https://github.com/wfxr/forgit.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/forgit
# for sheldon.cli
[plugins.forgit]
github = "wfxr/forgit"
rev = "25.02.0"
use = ["forgit.plugin.zsh"]
apply = ["source"]
# manually
# Clone the repository and source it in your shell's rc file or put bin/git-forgit into your $PATH
```
## Homebrew
To install using brew
```sh
brew install forgit
```
Then add the following to your shell's config file:
```sh
# Fish:
# ~/.config/fish/config.fish:
[ -f $HOMEBREW_PREFIX/share/forgit/forgit.plugin.fish ]; and source $HOMEBREW_PREFIX/share/forgit/forgit.plugin.fish
# Zsh:
# ~/.zshrc:
[ -f $HOMEBREW_PREFIX/share/forgit/forgit.plugin.zsh ] && source $HOMEBREW_PREFIX/share/forgit/forgit.plugin.zsh
# Bash:
# ~/.bashrc:
[ -f $HOMEBREW_PREFIX/share/forgit/forgit.plugin.sh ] && source $HOMEBREW_PREFIX/share/forgit/forgit.plugin.sh
```
## Arch User Repository
[AUR](https://wiki.archlinux.org/title/Arch_User_Repository) packages, maintained by the developers of forgit, are available. Install the [forgit](https://aur.archlinux.org/packages/forgit) package for the latest release or [forgit-git](https://aur.archlinux.org/packages/forgit-git) to stay up to date with the latest commits from the default branch of this repository.
# Completions
Forgit offers completions for all supported shells. Completions are automatically configured when installing forgit through Homebrew or the AUR. All other installation methods mentioned above require manual setup for completions. The necessary steps depend on the shell you use.
## Bash
- Put [`completions/git-forgit.bash`](https://github.com/wfxr/forgit/blob/main/completions/git-forgit.bash) in
`~/.local/share/bash-completion/completions` to have bash tab completion for `git forgit` and configured git aliases.
- Source [`completions/git-forgit.bash`](https://github.com/wfxr/forgit/blob/main/completions/git-forgit.bash) explicitly to have
bash tab completion for forgit shell functions and aliases (e.g., `gsw ` completes branches).
## Fish
- Put [`completions/git-forgit.fish`](https://github.com/wfxr/forgit/blob/main/completions/git-forgit.fish) in `~/.config/fish/completions/` to have fish tab completion for `git forgit` and configured git aliases, as well as shell command aliases, such as `ga`.
## Zsh
- Put [`completions/_git-forgit`](completions/_git-forgit) in a directory in your `$fpath` (e.g., `/usr/share/zsh/site-functions`) to have zsh tab completion for `git forgit` and configured git aliases, as well as shell command aliases, such as `forgit::add` and `ga`.
If you're having issues after updating, and commands such as `forgit::add` or aliases `ga` aren't working, remove your completions cache and restart your shell.
```zsh
> rm ~/.zcompdump
> zsh
```
# 📝 Features
- **Interactive `git add` selector** (`ga`)
- **Interactive `git log` viewer** (`glo`)
*The log graph can be disabled by option `FORGIT_LOG_GRAPH_ENABLE` (see discuss in [issue #71](https://github.com/wfxr/forgit/issues/71)).*
- **Interactive `.gitignore` generator** (`gi`)
- **Interactive `.gitattributes` generator** (`gat`)
- **Interactive `git diff` viewer** (`gd`)
- **Interactive `git show` viewer** (`gso`)
- **Interactive `git reset HEAD ` selector** (`grh`)
- **Interactive `git checkout ` selector** (`gcf`)
- **Interactive `git checkout ` selector** (`gcb`)
- **Interactive `git switch ` selector** (`gsw`)
- **Interactive `git branch -D ` selector** (`gbd`)
- **Interactive `git checkout ` selector** (`gct`)
- **Interactive `git checkout ` selector** (`gco`)
- **Interactive `git revert ` selector** (`grc`)
- **Interactive `git stash` viewer** (`gss`)
- **Interactive `git stash push` selector** (`gsp`)
- **Interactive `git clean` selector** (`gclean`)
- **Interactive `git cherry-pick` selector** (`gcp`)
- **Interactive `git rebase -i` selector** (`grb`)
- **Interactive `git reflog` viewer** (`grl`)
- **Interactive `git blame` selector** (`gbl`)
- **Interactive `git commit --fixup && git rebase -i --autosquash` selector** (`gfu`)
- **Interactive `git commit --squash && git rebase -i --autosquash` selector** (`gsq`)
- **Interactive `git commit --fixup=reword && git rebase -i --autosquash` selector** (`grw`)
# ⌨ Keybindings
| Key | Action |
| :-------------------------------------------: | ------------------------------------------- |
| Enter | Confirm |
| Tab | Toggle mark and move down |
| Shift - Tab | Toggle mark and move up |
| ? | Toggle preview window |
| Alt - W | Toggle preview wrap |
| Ctrl - S | Toggle sort |
| Ctrl - R | Toggle selection |
| Ctrl - Y | Copy commit hash/stash ID* |
| Ctrl - K / P | Selection move up |
| Ctrl - J / N | Selection move down |
| Alt - K / P | Preview move up |
| Alt - J / N | Preview move down |
| Alt - E | Open file in default editor (when possible) |
\* Available when the selection contains a commit hash or a stash ID.
For Linux users `FORGIT_COPY_CMD` should be set to make copy work. Example: `FORGIT_COPY_CMD='xclip -selection clipboard'`.
# ⚙ Options
Options can be set via environment variables. They have to be **exported** in
order to be recognized by `forgit`.
For instance, if you want to order branches in `gcb` by the last committed date you could:
```shell
export FORGIT_CHECKOUT_BRANCH_BRANCH_GIT_OPTS='--sort=-committerdate'
```
## shell aliases
You can change the default aliases by defining these variables below before sourcing the forgit shell plugin.
(To disable all aliases, Set the `FORGIT_NO_ALIASES` flag.)
``` bash
forgit_log=glo
forgit_reflog=grl
forgit_diff=gd
forgit_show=gso
forgit_add=ga
forgit_reset_head=grh
forgit_ignore=gi
forgit_attributes=gat
forgit_checkout_file=gcf
forgit_checkout_branch=gcb
forgit_switch_branch=gsw
forgit_branch_delete=gbd
forgit_checkout_tag=gct
forgit_checkout_commit=gco
forgit_revert_commit=grc
forgit_clean=gclean
forgit_stash_show=gss
forgit_stash_push=gsp
forgit_cherry_pick=gcp
forgit_rebase=grb
forgit_blame=gbl
forgit_fixup=gfu
forgit_squash=gsq
forgit_reword=grw
```
## git integration
You can use forgit as a sub-command of git by making `git-forgit` available in `$PATH`:
```sh
# after `forgit` was loaded
PATH="$PATH:$FORGIT_INSTALL_DIR/bin"
```
*Some plugin managers can help do this.*
Then, any forgit command will be a sub-command of git:
```cmd
git forgit log
git forgit add
git forgit diff
```
Optionally you can add [aliases in git](https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases):
```sh
git config --global alias.cf 'forgit checkout_file'
```
And use forgit functions via a git alias:
```sh
git cf
```
## git options
If you want to customize `git`'s behavior within forgit there is a dedicated variable for each forgit command.
These are passed to the according `git` calls.
| Command | Option |
| -------- | --------------------------------------------------------------------------- |
| `ga` | `FORGIT_ADD_GIT_OPTS` |
| `glo` | `FORGIT_LOG_GIT_OPTS` |
| `grl` | `FORGIT_REFLOG_GIT_OPTS` |
| `gd` | `FORGIT_DIFF_GIT_OPTS` |
| `gso` | `FORGIT_SHOW_GIT_OPTS` |
| `grh` | `FORGIT_RESET_HEAD_GIT_OPTS` |
| `gcf` | `FORGIT_CHECKOUT_FILE_GIT_OPTS` |
| `gcb` | `FORGIT_CHECKOUT_BRANCH_GIT_OPTS`, `FORGIT_CHECKOUT_BRANCH_BRANCH_GIT_OPTS` |
| `gsw` | `FORGIT_SWITCH_BRANCH_GIT_OPTS` |
| `gbd` | `FORGIT_BRANCH_DELETE_GIT_OPTS` |
| `gct` | `FORGIT_CHECKOUT_TAG_GIT_OPTS` |
| `gco` | `FORGIT_CHECKOUT_COMMIT_GIT_OPTS` |
| `grc` | `FORGIT_REVERT_COMMIT_GIT_OPTS` |
| `gss` | `FORGIT_STASH_SHOW_GIT_OPTS` |
| `gsp` | `FORGIT_STASH_PUSH_GIT_OPTS` |
| `gclean` | `FORGIT_CLEAN_GIT_OPTS` |
| `grb` | `FORGIT_REBASE_GIT_OPTS` |
| `gbl` | `FORGIT_BLAME_GIT_OPTS` |
| `gfu` | `FORGIT_FIXUP_GIT_OPTS` |
| `gsq` | `FORGIT_SQUASH_GIT_OPTS` |
| `grw` | `FORGIT_REWORD_GIT_OPTS` |
| `gcp` | `FORGIT_CHERRY_PICK_GIT_OPTS` |
## pagers
Forgit will use the default configured pager from git (`core.pager`,
`pager.show`, `pager.diff`) but can be altered with the following environment
variables:
| Use case | Option | Fallbacks to |
| ------------------------ | ------------------------- | ------------------------------------------------- |
| common pager | `FORGIT_PAGER` | `git config core.pager` _or_ `cat` |
| pager on `git show` | `FORGIT_SHOW_PAGER` | `git config pager.show` _or_ `$FORGIT_PAGER` |
| pager on `git diff` | `FORGIT_DIFF_PAGER` | `git config pager.diff` _or_ `$FORGIT_PAGER` |
| pager on `git blame` | `FORGIT_BLAME_PAGER` | `git config pager.blame` _or_ `$FORGIT_PAGER` |
| pager on `gitignore` | `FORGIT_IGNORE_PAGER` | `bat -l gitignore --color always` _or_ `cat` |
| pager on `gitattributes` | `FORGIT_ATTRIBUTES_PAGER` | `bat -l gitattributes --color always` _or_ `cat` |
| git log format | `FORGIT_GLO_FORMAT` | `%C(auto)%h%d %s %C(black)%C(bold)%cr%reset` |
## fzf options
You can add default fzf options for `forgit`, including keybindings, layout, etc.
(No need to repeat the options already defined in `FZF_DEFAULT_OPTS`)
``` bash
export FORGIT_FZF_DEFAULT_OPTS="
--exact
--border
--cycle
--reverse
--height '80%'
"
```
Customizing fzf options for each command individually is also supported:
| Command | Option |
|----------|-----------------------------------|
| `ga` | `FORGIT_ADD_FZF_OPTS` |
| `glo` | `FORGIT_LOG_FZF_OPTS` |
| `grl` | `FORGIT_REFLOG_FZF_OPTS` |
| `gi` | `FORGIT_IGNORE_FZF_OPTS` |
| `gat` | `FORGIT_ATTRIBUTES_FZF_OPTS` |
| `gd` | `FORGIT_DIFF_FZF_OPTS` |
| `gso` | `FORGIT_SHOW_FZF_OPTS` |
| `grh` | `FORGIT_RESET_HEAD_FZF_OPTS` |
| `gcf` | `FORGIT_CHECKOUT_FILE_FZF_OPTS` |
| `gcb` | `FORGIT_CHECKOUT_BRANCH_FZF_OPTS` |
| `gsw` | `FORGIT_SWITCH_BRANCH_FZF_OPTS` |
| `gbd` | `FORGIT_BRANCH_DELETE_FZF_OPTS` |
| `gct` | `FORGIT_CHECKOUT_TAG_FZF_OPTS` |
| `gco` | `FORGIT_CHECKOUT_COMMIT_FZF_OPTS` |
| `grc` | `FORGIT_REVERT_COMMIT_FZF_OPTS` |
| `gss` | `FORGIT_STASH_FZF_OPTS` |
| `gsp` | `FORGIT_STASH_PUSH_FZF_OPTS` |
| `gclean` | `FORGIT_CLEAN_FZF_OPTS` |
| `grb` | `FORGIT_REBASE_FZF_OPTS` |
| `gbl` | `FORGIT_BLAME_FZF_OPTS` |
| `gfu` | `FORGIT_FIXUP_FZF_OPTS` |
| `gsq` | `FORGIT_SQUASH_FZF_OPTS` |
| `grw` | `FORGIT_REWORD_FZF_OPTS` |
| `gcp` | `FORGIT_CHERRY_PICK_FZF_OPTS` |
Complete loading order of fzf options is:
1. `FZF_DEFAULT_OPTS` (fzf global)
2. `FORGIT_FZF_DEFAULT_OPTS` (forgit global)
3. `FORGIT_CMD_FZF_OPTS` (command specific)
Examples:
- `ctrl-d` to drop the selected stash but do not quit fzf (`gss` specific).
```sh
export FORGIT_STASH_FZF_OPTS='
--bind="ctrl-d:reload(git stash drop $(cut -d: -f1 <<<{}) 1>/dev/null && git stash list)"
'
```
- `ctrl-e` to view the logs in a vim buffer (`glo` specific).
```sh
export FORGIT_LOG_FZF_OPTS='
--bind="ctrl-e:execute(echo {} |grep -Eo [a-f0-9]+ |head -1 |xargs git show |vim -)"
'
```
## other options
| Option | Description | Default |
|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|
| `FORGIT_LOG_FORMAT` | git log format | `%C(auto)%h%d %s %C(black)%C(bold)%cr%Creset` |
| `FORGIT_PREVIEW_CONTEXT` | lines of diff context in preview mode | 3 |
| `FORGIT_FULLSCREEN_CONTEXT` | lines of diff context in full-screen mode | 10 |
| `FORGIT_DIR_VIEW` | command used to preview directories | `tree` if available, otherwise `find` |
| `FORGIT_CLEAN_LIST_FILES_OPTS` | arguments passed to `git ls-files` together with `--others` to determine which files are shown when invoking `forgit clean` | |
# 📦 Optional dependencies
- [`delta`](https://github.com/dandavison/delta) / [`diff-so-fancy`](https://github.com/so-fancy/diff-so-fancy): For better human-readable diffs.
- [`bat`](https://github.com/sharkdp/bat): Syntax highlighting for `gitignore` and `gitattributes`.
- [`emoji-cli`](https://github.com/wfxr/emoji-cli): Emoji support for `git log`.
- [`tree`](https://gitlab.com/OldManProgrammer/unix-tree): Directory tree view for `gclean`.
# 💡 Tips
- Most of the commands accept optional arguments (e.g., `glo develop`, `glo f738479..188a849b -- main.go`, `gco main`).
- `gd` supports specifying revision (e.g., `gd HEAD~`, `gd v1.0 README.md`).
- Call `gi` or `gat` with arguments to get the wanted `.gitignore`/`.gitattributes` contents directly (e.g., `gi cmake c++`).
# 📃 License
[MIT](https://wfxr.mit-license.org/2017) (c) Wenxuan Zhang