A CLI tool for tracking and quickly switching between git branches across projects. Git::Jump automatically tracks your branch history and lets you jump between recently visited branches with ease.
- Automatic Branch Tracking: Install a git hook to automatically track branches when you check them out
- Manual Branch Management: Add, list, and clear tracked branches
- Quick Branch Switching: Jump to the next branch or a specific branch by index
- Smart Branch Ordering: Branches are ordered by most recently visited
- Project-Specific Tracking: Separate branch history for each git repository
- Configurable Keep Patterns: Define which branches to keep when clearing (e.g., main, master, develop)
- XDG Base Directory Support: Configuration and data files follow XDG standards
- Beautiful Terminal Output: Colored output and formatted tables for easy reading
Install the gem by executing:
gem install git-jumpOr add it to your application's Gemfile:
bundle add git-jump- Initialize the configuration file:
git-jump setup- Navigate to a git repository and install the post-checkout hook:
cd /path/to/your/repo
git-jump install- Now branches will be automatically tracked when you check them out! Or add branches manually:
git-jump add feature/my-branch- List tracked branches:
git-jump list- Jump to the next branch in the list:
git-jump jump- Or jump to a specific branch by index:
git-jump jump 3Initialize the configuration file at ~/.config/git-jump/config.toml (or $XDG_CONFIG_HOME/git-jump/config.toml).
git-jump setupInstall the post-checkout git hook in the current repository. This enables automatic branch tracking whenever you checkout a branch.
cd /path/to/your/repo
git-jump installManually add a branch to tracking for the current project.
git-jump add feature/my-branchList all tracked branches for the current project. Branches are displayed with an index number and sorted by most recently visited.
git-jump listOutput example:
Tracked Branches
────────────────
┌─────┬────────────────┬──────────────┐
│ # │ Branch │ Last Visited │
├─────┼────────────────┼──────────────┤
│ → 1 │ feature/auth │ just now │
│ 2 │ feature/api │ 2 hours ago │
│ 3 │ master │ 1 day ago │
└─────┴────────────────┴──────────────┘
Jump to the next branch in the list, or to a specific branch by index.
# Jump to the next branch
git-jump jump
# Jump to branch at index 3
git-jump jump 3Clear branches that don't match the keep patterns defined in your configuration. This is useful for cleaning up old feature branches while preserving important branches like main, master, etc.
git-jump clearYou'll be prompted to confirm before clearing.
Show the current status, configuration, and tracking statistics.
git-jump statusOutput example:
Git Jump Status
───────────────
ℹ Project: my-project
ℹ Path: /Users/me/code/my-project
ℹ Current branch: feature/auth
Configuration
─────────────
ℹ Config file: /Users/me/.config/git-jump/config.toml
ℹ Config exists: Yes
ℹ Database: /Users/me/.local/share/git-jump/branches.db
ℹ Max branches: 20
ℹ Auto-track: Enabled
ℹ Keep patterns: ^main$, ^master$, ^develop$, ^staging$
Hook Status
───────────
ℹ Post-checkout hook: Installed
Tracking Statistics
───────────────────
ℹ Total branches tracked: 5
ℹ Most recent: feature/auth
Show the current version of git-jump.
git-jump versionAll commands support these global options:
--config PATHor-c PATH: Use a custom configuration file--quietor-q: Suppress output--verboseor-v: Enable verbose output
Example:
git-jump --config ~/my-config.toml list
git-jump -q jump
git-jump -v statusGit::Jump uses a TOML configuration file located at ~/.config/git-jump/config.toml (or $XDG_CONFIG_HOME/git-jump/config.toml).
Run git-jump setup to create the default configuration file.
[database]
# SQLite database location (defaults to XDG_DATA_HOME/git-jump/branches.db)
# You can use environment variables like $XDG_DATA_HOME or $HOME
path = "$XDG_DATA_HOME/git-jump/branches.db"
[tracking]
# Maximum number of branches to track per project
max_branches = 20
# Automatically track branches on checkout (via git hook)
auto_track = true
# Global branch patterns to always keep when clearing (regex patterns)
keep_patterns = ["^main$", "^master$", "^develop$", "^staging$"]
# Example project-specific configuration
# [[projects]]
# name = "my-project"
# path = "/path/to/my-project"
# keep_patterns = ["^main$", "^feature/.*$"]Keep patterns are regex patterns that define which branches should be preserved when running git-jump clear. By default, common main branches are kept:
^main$- main branch^master$- master branch^develop$- develop branch^staging$- staging branch
You can customize these patterns globally or per-project in your configuration file.
Git::Jump follows the XDG Base Directory Specification:
- Configuration:
$XDG_CONFIG_HOME/git-jump/config.toml(defaults to~/.config/git-jump/config.toml) - Data:
$XDG_DATA_HOME/git-jump/branches.db(defaults to~/.local/share/git-jump/branches.db) - Cache:
$XDG_CACHE_HOME/git-jump/(defaults to~/.cache/git-jump/)
# First time setup
git-jump setup
# In your project directory
cd ~/code/my-project
git-jump install
# Work on different branches
git checkout feature/authentication
git checkout feature/api
git checkout feature/ui
# List your tracked branches
git-jump list
# Output:
# Tracked Branches
# ────────────────
# ┌─────┬─────────────────────────┬──────────────┐
# │ # │ Branch │ Last Visited │
# ├─────┼─────────────────────────┼──────────────┤
# │ → 1 │ feature/ui │ just now │
# │ 2 │ feature/api │ 5 minutes ago│
# │ 3 │ feature/authentication │ 10 minutes ago│
# └─────┴─────────────────────────┴──────────────┘
# Jump to the next branch (feature/api)
git-jump jump
# Jump to a specific branch by index
git-jump jump 3 # Switches to feature/authentication
# Clean up old feature branches (keeps main/master/develop/staging)
git-jump clearGit::Jump tracks branches per project, so you can use it across all your repositories:
# Project A
cd ~/code/project-a
git-jump install
git checkout feature/new-ui
git checkout feature/refactor
# Project B
cd ~/code/project-b
git-jump install
git checkout bugfix/login
git checkout feature/dashboard
# Each project maintains its own branch history
cd ~/code/project-a
git-jump list # Shows only project-a branches
cd ~/code/project-b
git-jump list # Shows only project-b branches# Use a custom config file
git-jump --config ~/my-custom-config.toml status
# Run commands quietly (no output)
git-jump -q jump
# Verbose output for debugging
git-jump -v add feature/new-featureGit::Jump tracks your branch history in a SQLite database. Each time you check out a branch (with the hook installed) or manually add a branch, it's recorded in the database with:
- Project path and name
- Branch name
- Last visited timestamp
- Position in the branch list
Branches are automatically reordered based on when they were last visited, so the most recently used branches appear at the top of the list. This makes it easy to jump between branches you're actively working on.
When you run git-jump jump, it checks out the next branch in the list (or the branch at the specified index) and updates the last visited timestamp, moving it to the top of the list.
When you run git-jump install, it creates a post-checkout hook in .git/hooks/post-checkout that automatically tracks branches when you check them out using git checkout. The hook is safe and will not interfere with existing hooks if you chain them properly.
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/dsaenzriv/git-jump. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Git::Jump project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
Inspired by the need to quickly switch between feature branches during development. Architecture follows the modular design patterns from dotsync.