fzf-git-branches

A script to manage Git branches and worktrees using fzf in bash and zsh. It provides a convenient way to handle Git branches and worktrees with a fuzzy finder interface.

Features

List, delete, and switch to Git branches and worktrees.
Integrated with fzf for enhanced user interaction.
Support for confirmation dialogs.
ANSI output coloring for better readability.

Requirements

git (https://git-scm.com/)
fzf (https://github.com/junegunn/fzf)
Modern version of bash or zsh

Installation

Clone the repository or download the script.

git clone https://github.com/awerebea/fzf-git-branches.git ~/.fzf-git-branches

Source the script in your shell configuration file (.bashrc, .zshrc, etc.):
```
source ~/.fzf-git-branches/fzf-git-branches.sh
```
Ensure fzf is installed and available in your PATH.

Advanced Configuration

Default Options Overriding

The default values of FZF options are set as follows:

--height 80% \
--reverse \
--ansi \
--bind=ctrl-y:accept,ctrl-t:toggle+down \
--border=top \
--cycle \
--multi \
--pointer='' \
--preview 'FGB_BRANCH={1}; git log --oneline --decorate --graph --color=always \${FGB_BRANCH:1:-1}'

These defaults can be overridden by setting the FGB_FZF_OPTS environment variable.

The default branches sort order is -committerdate, but this can be overridden by setting the FGB_SORT_ORDER environment variable.

Similarly, the default date format is committerdate:relative, which can be overridden using FGB_DATE_FORMAT.

Lastly, the default author format is committername, could be redefined with FGB_AUTHOR_FORMAT.

Lazy Load

To reduce shell startup time, consider lazy loading the script by calling it instead of sourcing it automatically every time. Replace source ~/.fzf-git-branches/fzf-git-branches.sh in your shell rc file with the following code snippet. This snippet defines several functions and aliases that load the script only when needed:

# Check if the script is installed
if [ -f "$HOME/.fzf-git-branches/fzf-git-branches.sh" ]; then
    lazy_fgb() {
        unset -f fgb gbl gbm gwl gwa gwm gwt lazy_fgb
        if ! source "$HOME/.fzf-git-branches/fzf-git-branches.sh"; then
            echo "Failed to load fzf-git-branches" >&2
            return 1
        fi
        alias gbl='fgb branch list'
        alias gbm='fgb branch manage'
        alias gwl='fgb worktree list'
        alias gwm='fgb worktree manage'
        alias gwa='fgb worktree add --confirm'
        alias gwt='fgb worktree total --confirm'
        fgb "$@"
    }
    function fgb() {
        lazy_fgb "$@"
    }
    function gbl() {
        lazy_fgb branch list "$@"
    }
    function gbm() {
        lazy_fgb branch manage "$@"
    }
    function gwl() {
        lazy_fgb worktree list "$@"
    }
    function gwm() {
        lazy_fgb worktree manage "$@"
    }
    function gwa() {
        lazy_fgb worktree add --confirm "$@"
    }
    function gwt() {
        lazy_fgb worktree total --confirm "$@"
    }
fi

Lazy Load Explanation

This snippet defines a lazy loading function lazy_fgb and related functions that wrap the lazy_fgb function call with corresponding commands, subcommands, and any additional arguments provided:

lazy_fgb: The main function responsible for lazy loading fzf-git-branches.sh and executing commands based on arguments passed to it.
fgb: Calls lazy_fgb with any arguments.
gbl: Calls lazy_fgb with the command branch list.
gbm: Calls lazy_fgb with the command branch manage.
gwl: Calls lazy_fgb with the command worktree list.
gwm: Calls lazy_fgb with the command worktree manage.
gwa: Calls lazy_fgb with the command worktree add --confirm.
gwt: Calls lazy_fgb with the command worktree total --confirm.

Here’s how it works:

Lazy Loading Function lazy_fgb: On its first call, lazy_fgb unsets itself and all related functions. It then sources the fzf-git-branches.sh script to load its functionality.

Lazy Loading Function (lazy_fgb): Upon its initial invocation, lazy_fgb unsets itself and all associated functions. It subsequently sources the fzf-git-branches.sh script to load its functionality.

Aliases for Convenience: To replace the functions that were unset earlier, lazy_fgb establishes aliases with identical names corresponding to commonly used commands provided by the script. These aliases simplify the execution of the script’s commands, enhancing usability and efficiency.

Customization: Users can edit or expand the aliases as needed for their specific requirements.

This approach enhances shell startup efficiency by loading scripts only when necessary, while the predefined aliases streamline command execution once the script is loaded.

Usage

To start using the script, call the fgb function in your terminal with a command and its options as arguments.

Examples

Manage branches:

fgb branch manage

Screenshot

Manage worktrees:

fgb worktree total

Screenshot

This will open a fzf interface to manage your Git branches.

Key Bindings

Default key bindings that can be overridden by FGB_FZF_OPTS environment variable:

enter/ctrl-y: Select the branch/worktree to jump to.
ctrl-t: Toggle the selection.

After invoking fzf, the following key bindings are expected (and can be redefined by the
FGB_BINDKEY_DEL, FGB_BINDKEY_EXTEND_DEL, FGB_BINDKEY_INFO, FGB_BINDKEY_VERBOSE environment variables respectively):

ctrl-d: Delete the selected branch.

Screenshot
ctrl-alt-d: Extended delete. When deleting a worktree, delete the associated local branch; when deleting a local branch, delete the remote branch.

Screenshot
ctrl-o: Show branch information.

Screenshot
ctrl-v: Use verbose mode to prompt for user confirmation of the directory name for the new worktree, even when this confirmation is suppressed by the -c, --confirm option.

Screenshot

Available Commands and Subcommands

Branch Commands

fgb branch list [args]: Lists the Git branches in the repository and exit.
fgb branch manage [args]: Switch to existing branches in the git repository, delete them, or get information about branches.

Worktree Commands

fgb worktree list [args]: Lists all worktrees in a bare Git repository and exit.
fgb worktree manage [args]: Switch to existing worktrees in the bare Git repository or delete them.
fgb worktree add [args]: Add a new worktree based on a selected Git branch.
fgb worktree total [args]: Total control over worktrees. Add a new one, switch to an existing worktree in the bare Git repository, or delete them, optionally with corresponding branches.

Available options used in commands in appropriate combinations.

By default, all commands list only local branches.
-r, --remotes: Lists only remote branches.

Screenshot
-a, --all: Lists both local and remote branches.

Screenshot
-s, --sort: Sort branches by :
- -committerdate (default )
- refname
- authorname
- etc.
-f, --force: Suppress confirmation dialog for non-destructive operations
-c, --confirm: Automatic confirmation of the directory name for the new worktree
-d, --date-format: Format for 'date' string:
- committerdate:relative (default)
- %(authordate) %(committerdate:short)
- authordate:(relative|local|default|iso|iso-strict|rfc|short|raw)
- authordate:format:'%Y-%m-%d %H:%M:%S'
- committerdate:format-local:'%Y-%m-%d %H:%M:%S'
-u, --author-format: Format for 'author' string:
- committername (default)
- authoremail
- %(committername) %(committeremail)
- %(authorname) %(authormail) / %(committername) %(committeremail)

Screenshot

For more details on each command and its options, you can use the -h or --help option. For example:

fgb branch manage --help

Screenshot

License

This script is licensed under the GPL License. See the LICENSE file for more details.

Contribution

Feel free to open issues or submit pull requests if you find bugs or have suggestions for improvements.

Inspiration

Inspired by fzf-marks and git-worktree.nvim.