- gitBranchTool
A bash tool to facilitate managing git branches with long cryptic names with aliases
The gitBranchTool, g, command provides additional functionalities around working with git branches.
If you frequently work with long branch names that include developer names, project names, issue numbers, and etc this tool is for you. With gitBranchTool or g, you'll be able to assign alias names for each branch.
You can monitor, switch, and delete your branches using the aliases instead of the long and confusing branch names (g commands support both branch names and aliases, so you wouldn't have to use git for any of your branch switching needs).
Additionally, You can add notes to each branch to fully remember what they were about so you can keep the aliases shorter. You can list branches with their aliases and notes at anytime.
g also provides auto-completion for branch names and aliases, so you wouldn't even have to type the full alias name.
On top of all these, g provides a custom prompt that displays the name of the current repository, sub-directory, branch name, and its alias.
-
Download the artifact
g-linux-vX.X.Xfrom the latest release here -
Add the binary to your PATH environment variable (or to a directory that is already in your PATH)
A directory that is already in your PATH is
/usr/local/bin/or/usr/bin/
sudo mv g-linux-vX.X.X /usr/local/bin/g- Ensure the binary has the correct permissions
sudo chmod 755 /usr/local/bin/g-
Download the artifact
g-macos-vX.X.Xfrom the latest release here -
Add the binary to your PATH environment variable (or to a directory that is already in your PATH)
A directory that is already in your PATH is
/usr/local/bin/or/usr/bin/
sudo mv g-macos-vX.X.X /usr/local/bin/g- Ensure the binary has the correct permissions
sudo chmod 755 /usr/local/bin/g-
Download the artifact
g-win-vX.X.Xfrom the latest release here -
Add the binary to your PATH environment variable (or to a directory that is already in your PATH)
A directory that is already in your PATH is
C:\Windows\System32\(you may need to run PowerShell as an administrator)
Move-Item -Force -Path .\g-win-vX.X.X.exe -Destination C:\Windows\System32\g.exeFor auto-completion, you can run the following commands based on your shell:
sudo mkdir -p /etc/bash_completion.d && sudo touch /etc/bash_completion.d/g && USER=$(whoami); sudo chown $USER /etc/bash_completion.d/g && sudo chmod 755 /etc/bash_completion.d/g && sudo g completion bash > /etc/bash_completion.d/g"echo "\nautoload -U compinit; compinit" >> ~/.bashrc
sudo mkdir -p /etc/bash_completion.d && sudo touch /etc/bash_completion.d/g && USER=$(whoami); sudo chown $USER /etc/bash_completion.d/g && sudo chmod 755 /etc/bash_completion.d/_g && sudo g completion bash > /etc/bash_completion.d/g"sudo mkdir -p ${fpath[1]} && sudo touch ${fpath[1]}/_g && USER=$(whoami); sudo chown $USER ${fpath[1]}/_g && sudo chmod 755 ${fpath[1]}/_g && sudo g completion zsh > "${fpath[1]}/_g"echo "\nautoload -U compinit; compinit" >> ~/.zshrc
sudo mkdir -p ${fpath[1]} && sudo touch ${fpath[1]}/_g && USER=$(whoami); sudo chown $USER ${fpath[1]}/_g && sudo chmod 755 ${fpath[1]}/_g && sudo g completion zsh > "${fpath[1]}/_g"For default PowerShell profile file, run the following command:
echo "g completion powershell | Out-String | Invoke-Expression" >> $PROFILERun the following command to add the gitBranchTool custom prompt to your shell profile file:
- Change
.bashrcwith.zshrcif you use ZSH, or the profile file you use if it's different.
echo -e "\nPROMPT_COMMAND='export PS1=\"\$(g _ps)\"'\nprecmd() { eval \"\$PROMPT_COMMAND\"; }" >> ~/.bashrcRun the following command to add the gitBranchTool custom prompt to your PowerShell profile file:
echo "function prompt { g _ps }" >> $PROFILEA bash tool to facilitate managing git branches with long cryptic names with aliases
Usage:
g [command]
Available Commands:
addAlias Adds alias and note to a branch that is not stored yet
completion Generate the autocompletion script for the specified shell
create Creates a branch with name, alias, and note, and checks into it
currentBranch Returns the name of active branch with alias and note
delete Deletes listed branches base on name or alias
get Get configuration options (Run `g get --help` for more information)
getBranchAlias Gets the branch alias
help Help about any command
list Lists all branches with their name, alias, and notes
man Prints an LLM-friendly guide on how to use this tool
merge Merges or rebases the given branch into the current branch
removeEntry Removes a registered branch entry without deleting the branch
rename Updates the alias for the given branch name
resolveAlias Resolves the branch name from an alias
set Set configuration options (Run `g set --help` for more information)
switch Switches to the branch with the given name or alias
updateBranchNote Adds/updates the notes for a branch base on name/alias
upgrade Checks if a newer version is available
worktree Manage git worktrees (Run `g worktree --help` for more information)
Flags:
-h, --help help for g
-N, --no-log no logs
-V, --verbose verbose output
-v, --version version for g
Use "g [command] --help" for more information about a command.g man (alias g manual) prints a concise, LLM-friendly guide describing how to use the tool. It is meant to be dropped into an AI assistant's context so it can drive g without reading every --help page.
By default it documents only the core commands (create, delete, switch, merge, currentBranch, list, worktree) — the minimum needed to be productive. Pass --full to document every command instead.
| Command | Alias | Description |
|---|---|---|
g man |
g manual |
Print the guide for the core commands |
g man --full |
g man -f |
Print the guide for every command |
The guide is assembled from a short manual that each command carries, and always reminds the reader to run g <command> --help for full flag-level details.
g merge [NAME/ALIAS] (alias g m) merges — or, with --rebase, rebases — the given branch into the current branch, resolving the argument through your branch aliases. With no argument it uses the configured default branch, making g merge a quick way to update the current branch with the latest of main.
| Command | Alias | Description |
|---|---|---|
g merge NAME/ALIAS |
g m NAME/ALIAS |
Merge the given branch into the current branch (git merge) |
g merge |
g m |
Merge the configured default branch into the current branch |
g merge NAME/ALIAS --rebase |
g m NAME/ALIAS -r |
Rebase the current branch onto the given branch (git rebase) |
g merge --continue / g merge --abort |
Continue/abort an in-progress merge or rebase |
| Flag | Short | Description |
|---|---|---|
--rebase |
-r |
Use git rebase instead of git merge |
--squash |
-s |
Squash the merged commits (git merge --squash; incompatible with --rebase) |
--no-verify |
-n |
Skip git hooks (git merge --no-verify; incompatible with --rebase) |
--fetch |
-f |
Fetch the latest of the branch from origin before merging/rebasing |
--ff-only |
Refuse to merge unless it can be fast-forwarded (incompatible with --rebase) |
|
--no-ff |
Always create a merge commit (incompatible with --rebase) |
|
--abort |
Abort an in-progress merge or rebase | |
--continue |
Continue an in-progress merge or rebase after resolving conflicts |
When a merge or rebase stops due to conflicts, resolve them and run g m --continue to finish, or g m --abort to cancel. git's output (conflicts, editor) streams directly to your terminal, so it behaves exactly like running git by hand.
Git worktrees allow you to have multiple working directories attached to the same repository, enabling you to work on different branches simultaneously without switching. gitBranchTool provides first-class support for managing worktrees with the same alias/note workflow you use for branches.
All worktree features are opt-in and do not affect users who don't use worktrees.
| Command | Alias | Description |
|---|---|---|
g worktree |
g w |
Shows worktree help and lists all worktrees |
g worktree create ALIAS [BRANCH] [...NOTE] |
g w c |
Create a new worktree |
g worktree list |
g w l |
List all worktrees (registered and unregistered) |
g worktree delete [...PATH|ALIAS] [--force] |
g w d |
Delete worktree(s) by alias or path |
g worktree prune |
g w p |
Remove stale worktree entries |
g worktree create behavior:
- If
BRANCHis provided and matches a registered branch (by name or alias), the worktree is created for that branch and the branch is auto-registered if not already. - If
BRANCHis provided but not found in registered branches, the worktree is created with that branch as-is. If the branch doesn't exist in git, a new branch is created but is not automatically registered (useg addAlias <branch> <alias>to register it). - If
BRANCHis omitted, a new branch is created using the alias as the branch name.
g worktree list shows all worktrees from git worktree list, including those created outside of gitBranchTool. Registered worktrees display their alias and note.
g worktree delete accepts both aliases and full paths, so you can delete worktrees created outside of gitBranchTool as well.
g worktree prune runs git worktree prune first, then removes any stored entries whose paths no longer exist.
Existing branch commands support an optional -w flag for worktree integration:
| Command | Description |
|---|---|
g create NAME ALIAS [...NOTE] -w |
Create a new branch and a worktree for it (branch is not checked out in the current directory) |
g create NAME ALIAS [...NOTE] -w=WT_ALIAS |
Same as above, but with a custom worktree alias |
g switch NAME/ALIAS -w |
Find the worktree for a branch and print its path. If no worktree exists, create one |
g delete NAME/ALIAS -w |
Delete a branch and its associated worktree |
g list |
When worktrees exist, the branch list shows a "Worktree" column with the alias or path |
Note: To specify a custom worktree alias with
-w, use the=syntax:-w=my-alias. The space-separated form (-w my-alias) is not supported due to CLI parsing limitations.
| Setting | Command | Description |
|---|---|---|
worktree-path |
g set worktree-path <TEMPLATE> |
Path template for new worktrees. Available variables: {repository}, {alias}, {branch}. Default: ./worktrees/{alias} |
delete-branches-worktree |
g set delete-branches-worktree <true|false|null> |
Controls worktree deletion when a branch is deleted. true: auto-delete, false: never delete, null: prompt (default) |
Retrieve settings with g get worktree-path and g get delete-branches-worktree.
- Create a branch
g c cyrus/jira-60083 banner "Adds banner to the home page"- Add alias to existing branch
g a cyrus/jira-60083 banner "Adds banner to the home page"- List all branches
g l- List registered and unregistered branches
With --all/-a, the registered branches are listed first (with their alias and note), followed by every other local git branch with an empty alias and note.
g l -a- Switch to branch
g s banner- Delete branch
g d banner- Delete multiple branches
g d banner cyrus/jira-50930- Delete branches matching a regular expression
With --regex/-e, the arguments are treated as regular expressions and every registered branch whose name or alias matches is deleted.
g d -e "claude.*"
g d -e "cyrus/.*" "rel-[1-3]/beta"- Delete branches that are not registered with
g
With --all/-a, the candidate list is expanded with every local git branch before the search runs, so branches that were never registered with g can be deleted by name or by regex. Combine it with -e to clean up unregistered branches in bulk.
g d -a old-experiment
g d -a -e "claude/.*"- Set branch name prefix for current repository
g set local-prefix dev/- Upgrade the tool to latest version
g upgrade -y- Create a worktree for an existing branch
g w c my-feature feature/my-feature "Working on login page"- Create a worktree with a new branch (alias becomes the branch name)
g w c quick-fix- List all worktrees
g w l- Delete a worktree by alias
g w d my-feature- Force delete a worktree with uncommitted changes
g w d my-feature -f- Delete multiple worktrees
g w d my-feature bugfix-123- Delete an unregistered worktree by path
g w d /path/to/worktree- Prune stale worktree entries
g w p- Create a branch and worktree together
g c feature/auth auth "Auth system" -w- Find or create a worktree when switching
g s feature/auth -w- Delete a branch and its worktree
g d auth -w- Customize the worktree path template
g set worktree-path "../{repository}-worktrees/{alias}"- Auto-delete worktrees when branches are deleted
g set delete-branches-worktree trueThis repository is open for contributions. If you have any suggestions or issues, please open an issue or a pull request.
In your pull request, please include a description of the changes you made and why you made them, and update the CHANGE_LOGS.md, VERSION, and README.md (to contributors section) files accordingly.
Please use the Conventional Commits 1.0.0 specification for all commit messages and pull request titles. Format your messages as follows: ():
- feat: A new feature for the user.
- fix: A bug fix for the user.
- chore: Routine tasks, maintenance, or dependency updates.
- docs: Documentation changes only.
- refactor: Code changes that neither fix a bug nor add a feature.
Example: feat(auth): add google oauth2 login flow
This project is licensed under the MIT License
Copyright 2026 - Cyrus Mobini (@cyrus2281)