git-switch

A fast, interactive terminal UI for switching between git branches. Built with tcell for a smooth, cross-platform experience.

Switching branches with git checkout or git switch can be slow, especially in repositories with many branches. git-switch makes it easy to quickly find and switch branches with just a few keystrokes.

Features

• Fuzzy search: Instantly filter branches as you type.
• Pinned Branches: A configurable list of branches that will always show at the top of the list.
• Keyboard navigation: Use arrow keys to move, Enter to switch, and Esc/Ctrl+C to quit.
• Git Checkout: Works as a stand-in replacement for the git checkout command.
• Custom Impelementation: Works as a general branch selector that can return to stdout.
• Public API: Can be easily integrated into your own Go projects.

Installation

go install github.com/nathan-fiscaletti/git-switch@latest

Note

git-switch by default installs as the command git-switch. I highly recommend that you alias the git-switch command to sw in your shell for ease-of-use. The rest of this documentation will make the assumption that you have. If not, use git-switch instead of sw for each command.

# Windows Powershell
"`nset-alias sw git-switch" | out-file -append -encoding utf8 $profile; . > $profile

# Bash (use .zshrc for zsh, etc.)
echo "alias sw='git-switch'" >> ~/.bashrc && source ~/.bashrc

Usage

Interactive Mode

Just run:

sw

• Start typing to filter branches.
• Use Up/Down arrows to select.
• Press Enter to checkout the selected branch.
• Press Esc or Ctrl+C to exit.
• Press CTRL+D to pin the currently selected branch.
• Press CTRL+U to unpin the currently selected branch.

Git Checkout Override

Arguments passed to git-switch are automatically forwarded to git checkout.

# Checkout a branch
sw <branch-name>
# Create a new branch
sw -b <branch-name>
# etc...

Internal Commands

Tip

Passing -x to git-switch will tell it you are executing an internal command.

Pinned Branches

A pinned branch always shows at the top of the list of branches in the switcher.

# While a branch is checked out
sw -x pin
sw -x unpin

By default, the currently checked out branch will be pinned/un-pinned. If you wish to pin/un-pin another branch, you can pass it in as an optional parameter.

sw -x pin <branch>
sw -x unpin <branch>

You can clear all pinned branches by running

sw -x unpin all

Popping branches

Any time you change branches using git-switch, your previous branch is stored. You can get back to it easily by using the pop command.

sw -x pop

Warning

If you check out a branch using git directly, git-switch will not be aware of the change. If you intend to use sw -x pop, you should always switch branches using git-switch.

Using git-switch as a general branch selector

You can use git-switch to select a branch and have the selected branch returned to the caller.

When using this mode the branch will not be automatically checked out, but instead printed to stdout.

# Windows Powershell
$branch = sw -x pipe
echo $branch

# Bash
branch=$(sw -x pipe)
echo $branch

Using the interactive branch selector in your own project

Install the package in your project using

go get github.com/nathan-fiscaletti/git-switch

The interactive branch selector is exposed in the pkg package.

package main

import (
    "fmt"
    sw "github.com/nathan-fiscaletti/git-switch/pkg"
)

func main() {
    // Your branch data
    currentBranch := "main"
    branches := []string{"main", "develop", "feature/new-api", "bugfix/issue-123"}
    pinnedBranches := []string{"main", "develop"}

    branchSelector, err := sw.NewBranchSelector(sw.BranchSelectorArguments{
        CurrentBranch:      currentBranch,
        Branches:           branches,
        PinnedBranches:     &pinnedBranches, // Pass as pointer for shared state
        PinnedBranchPrefix: "★",
        WindowSize:         10,
        SearchLabel:        "search branch",
        
        // Optional: Handle pin/unpin operations
        OnPinBranch: func(branch string) error {
            // Implement your own storage logic
            fmt.Printf("Pinning branch: %s\n", branch)
            // Save to database, file, etc.
            return nil
        },
        OnUnpinBranch: func(branch string) error {
            // Implement your own storage logic
            fmt.Printf("Unpinning branch: %s\n", branch)
            // Remove from database, file, etc.
            return nil
        },
    })
    if err != nil {
        panic(err)
    }

    // Show the interactive selector
    selectedBranch, err := branchSelector.PickBranch()
    if err != nil {
        panic(err)
    }

    if selectedBranch != "" {
        fmt.Printf("Selected branch: %s\n", selectedBranch)
        // Process the selected branch...
    }
}

Interactive Features

The branch selector includes interactive hotkeys:

• CTRL+D: Pin the currently selected branch
• CTRL+U: Unpin the currently selected branch
• Up/Down: Navigate branches
• Enter: Select branch
• Esc/Ctrl+C: Exit

Pin/unpin operations automatically call your OnPinBranch and OnUnpinBranch callbacks, allowing you to integrate with any storage backend (database, files, APIs, etc.).

Configuration

Config File Location:

Windows:  %APPDATA%\.gitswitch\config
Linux:    $HOME/.config/.gitswitch/config
macOS:    $HOME/Library/Application Support/.gitswitch/config

Configuration Values:

• window-size: The maximum number of branches to display at one time. (Default: 10)
• pinned-branch-prefix: The prefix to display before pinned branches. (Default: ★)
• prune-remote-branches: Will automatically run git remote prune for each remote before listing branches. (Default: false)

License

MIT (See LICENSE)