💤 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

Make sure you have fzf installed.

# 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

# 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

brew install forgit

Then add the following to your shell's config file:

# 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 packages, maintained by the developers of forgit, are available. Install the forgit package for the latest release or forgit-git to stay up to date with the latest commits from the default branch of this repository.

📝 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).

• Interactive .gitignore generator (gi)

• Interactive git diff viewer (gd)

• Interactive git reset HEAD <file> selector (grh)

• Interactive git checkout <file> selector (gcf)

• Interactive git checkout <branch> selector (gcb)

• Interactive git branch -D <branch> selector (gbd)

• Interactive git checkout <tag> selector (gct)

• Interactive git checkout <commit> selector (gco)

• Interactive git revert <commit> 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)

⌨ 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:

export FORGIT_CHECKOUT_BRANCH_BRANCH_GIT_OPTS='--sort=-committerdate'

shell aliases

You can change the default aliases by defining these variables below. (To disable all aliases, Set the FORGIT_NO_ALIASES flag.)

forgit_log=glo
forgit_reflog=grl
forgit_diff=gd
forgit_add=ga
forgit_reset_head=grh
forgit_ignore=gi
forgit_checkout_file=gcf
forgit_checkout_branch=gcb
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

git integration

You can use forgit as a sub-command of git by making git-forgit available in $PATH:

# 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:

git forgit log
git forgit add
git forgit diff

Optionally you can add aliases in git:

git config --global alias.cf 'forgit checkout_file'

And use forgit functions via a git alias:

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
grh	FORGIT_RESET_HEAD_GIT_OPTS
gcf	FORGIT_CHECKOUT_FILE_GIT_OPTS
gcb	FORGIT_CHECKOUT_BRANCH_GIT_OPTS, FORGIT_CHECKOUT_BRANCH_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
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
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)

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
gd	FORGIT_DIFF_FZF_OPTS
grh	FORGIT_RESET_HEAD_FZF_OPTS
gcf	FORGIT_CHECKOUT_FILE_FZF_OPTS
gcb	FORGIT_CHECKOUT_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
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).

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

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

📦 Optional dependencies

• delta / diff-so-fancy: For better human-readable diffs.

• bat: Syntax highlighting for gitignore.

• emoji-cli: Emoji support for git log.

Completions

Bash

• Put 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 explicitly to have bash tab completion for forgit shell functions and aliases (e.g., gcb <tab> completes branches).

Zsh

• Put 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.

> rm ~/.zcompdump
> zsh

💡 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 with arguments to get the wanted .gitignore contents directly(e.g., gi cmake c++).

📃 License

MIT (c) Wenxuan Zhang