Making it easier to work with Git on the command-line.
Git Helper is a single static binary that runs on macOS (Apple Silicon and Intel), Linux (amd64 and arm64), and Windows (amd64 and arm64). It needs git on your PATH. On Windows, install Git for Windows.
Testing status: Git Helper is developed and used day to day on macOS with Apple Silicon. The Intel macOS, Linux and Windows builds are compiled and run through the automated test suite on real GitHub-hosted machines for each of those platforms on every change, but they have not been tried by hand on physical hardware. If you run into a platform-specific problem, please open an issue.
You can download a pre-built binary straight from GitHub Releases if there is one for your platform. Currently, only binaries for macOS on Apple Silicon (git-helper_darwin_arm64) are published. The other platforms are compiled on every change to prove they build, and the tests run on them, but they are not published yet. On those platforms, build from source as described below, or open an issue.
After downloading, follow the steps under Installing to move it onto your PATH and make it executable. The examples there assume the binary is in your current directory, so either cd to where it downloaded (e.g. cd ~/Downloads) or adjust the paths.
Building locally requires Go, Task, and GoReleaser. The exact Go and GoReleaser versions the project uses are in .tool-versions, so with asdf you can run asdf install from the root directory of this repository.
To build for every supported platform into dist/, run this from the root directory of this repository:
task buildGoReleaser puts each binary in its own directory, named dist/<build>_<os>_<arch>/git-helper (with .exe on Windows), e.g. dist/matrix_linux_amd64_v1/git-helper. Locally built binaries report a snapshot version such as 1.0.4-SNAPSHOT-1a2b3c4.
To build only for your machine, without Task or GoReleaser, you can also run go build -o git-helper . (this reports its version as dev).
Move the binary for your platform onto your PATH as git-helper. The examples assume the binary is in your current directory.
sudo mv git-helper_darwin_arm64 /usr/local/bin/git-helper # git-helper_darwin_amd64 on Intel
sudo chown $(whoami):staff /usr/local/bin/git-helper
sudo chmod +x /usr/local/bin/git-helperThe first time you run a downloaded binary, macOS may block it with a message that it can't be verified. Binaries are not signed or notarized. If you trust the binary and wish to continue, follow Apple's steps for opening an app that was blocked:
- Run
git-helperonce, so macOS shows the warning and registers the block - Open System Settings and click Privacy & Security
- Scroll down and click Open Anyway next to the message about
git-helper - When the warning appears again, click Open
Per Apple, macOS then saves git-helper as an exception, and you can run it normally from then on.
These installation instructions have not been tried by hand on physical hardware. If you run into a platform-specific problem, please open an issue.
# Without root, if ~/.local/bin is on your PATH
install -m 0755 git-helper_linux_amd64 ~/.local/bin/git-helper # git-helper_linux_arm64 on ARM
# Or system-wide
sudo install -m 0755 git-helper_linux_amd64 /usr/local/bin/git-helperThese installation instructions have not been tried by hand on physical hardware. If you run into a platform-specific problem, please open an issue.
New-Item -ItemType Directory -Force "$env:USERPROFILE\bin" | Out-Null
Move-Item git-helper_windows_amd64.exe "$env:USERPROFILE\bin\git-helper.exe" # git-helper_windows_arm64.exe on ARM
$dir = "$env:USERPROFILE\bin"
$parts = @([Environment]::GetEnvironmentVariable("Path", "User") -split ";" | Where-Object { $_ })
if ($parts -notcontains $dir) { [Environment]::SetEnvironmentVariable("Path", (($parts + $dir) -join ";"), "User") }Then open a new terminal. Windows SmartScreen may warn about an unsigned binary the first time; choose More info and then Run anyway.
Assuming you already have Go's Git Helper installed, to update your version of Git Helper to the latest version available in GitHub, you can run:
git-helper updateThis replaces the git-helper binary that is currently running. To replace a binary somewhere else, pass --install-path. If the directory is not writable by your user (e.g. /usr/local/bin on macOS and Linux), it asks for your sudo password. Windows never needs sudo; the old binary is renamed to git-helper.exe.old and removed the next time you run update.
The update downloads the asset matching your OS and architecture from the latest release, so it only works on platforms that have published binaries (see above). On macOS you may need to allow the new binary as described above.
Some of the commands can be used without any additional configuration. However, others utilize special GitHub or GitLab configuration. To set up access with GitHub/GitLab, run:
git-helper setupThis will show a checklist of every supported provider (GitHub, GitLab) so you can pick any number of them to set up credentials for in one go, as well as give you the choice to set up Git Helper as a plugin or not (see below).
If ~/.git-helper/config.yml already exists, git-helper setup asks what you want to do:
- Add a new account -- appends one account for a provider you pick, without touching any account already configured. The normal way to add a second account later, e.g. a work account alongside a personal one.
- Edit or remove an account -- pick a provider, then pick which configured account (by username), then either update its token/
remote_hosts/api_host(re-asking everything fresh) or delete it. The normal way to rotate an expired token, rename an account, or drop a stale one. - Replace everything -- starts over from scratch, discarding every existing account.
- Leave it as is.
The final result will be a ~/.git-helper/config.yml file (in your home directory on every OS, e.g. C:\Users\you\.git-helper\config.yml on Windows) that only your user can read, with the contents in this form:
providers:
- name: github
username: GITHUB-USERNAME
token: GITHUB-TOKEN
- name: gitlab
username: GITLAB-USERNAME
token: GITLAB-TOKENTo create or see what personal access tokens (PATs) you have, look here:
- GitHub (
github.com): https://github.com/settings/tokens - GitLab (
gitlab.com): https://gitlab.com/-/profile/personal_access_tokens
You could either have one set of tokens for each computer you use, or just have one set of tokens for all computers that you rotate periodically.
Both GitHub and GitLab support more than one providers entry, so you can keep several accounts side by side -- a public account, a GitHub Enterprise or self-hosted GitLab account, even two accounts that are both just the public URL (e.g. a personal account and a work account). code-request works out which account to use from the current repo's remote, asking you to pick when more than one could apply.
Each account entry has two independent, optional settings, and it's important not to confuse them:
remote_hosts-- the host(s)code-requestshould recognize in a git remote (git@HOST:owner/repo.gitorhttps://HOST/owner/repo.git) as belonging to this account. Leave it out entirely if this account is simply the provider's public URL. This can be a real second domain (e.g. GitHub Enterprise or self-hosted GitLab), or it can be nothing more than a name you invented in your own~/.ssh/configto tell two accounts on the same real host apart (see below). Either way,remote_hostsby itself changes nothing about where API calls go.api_host-- the real server this account's API calls (creating a pull/merge request) should be sent to. Leave it out unless this account's provider is genuinely a different server than the public one. An account with noapi_hostalways talks to the real public API, even ifremote_hostslists something that looks like a different domain.
Example 1: a genuinely different server (e.g. GitHub Enterprise or self-hosted GitLab). Here remote_hosts and api_host name the same real domain, because remotes for this account really do point at a different server, and API calls for it really do need to go there too:
providers:
- name: gitlab
username: WORK-USERNAME
token: WORK-TOKEN
remote_hosts:
- gitlab.example.com
- git.internal.example.com # An alternate hostname for the same self-hosted instance
api_host: gitlab.example.comExample 2: two accounts on the same real host (e.g. personal + work, both on github.com). A plain git remote (git@github.com:...) carries no account identity, so there's nothing in it to tell two such accounts apart automatically. The standard git-native fix is an SSH config alias -- in ~/.ssh/config:
Host github.com-work
HostName github.com
User git
IdentityFile ~/.ssh/id_work
... then clone/configure that remote as git@github.com-work:org/repo.git. github.com-work is a name that exists only on your machine; GitHub itself has never heard of it. List it as a remote_hosts entry so code-request recognizes it, but do not set api_host -- there is no "github.com-work" server to call, so leaving api_host out keeps this account talking to the real api.github.com:
providers:
- name: github
username: PERSONAL-USERNAME
token: PERSONAL-TOKEN
# no remote_hosts -> this is simply the public github.com
- name: github
username: WORK-USERNAME
token: WORK-TOKEN
remote_hosts:
- github.com-work # an SSH alias -- not a real GitHub server, so no api_hostIf you don't bother with an SSH alias and just configure two accounts with no remote_hosts at all, code-request can't tell them apart from the remote alone -- in --interactive mode (the default) it'll ask which account to use; with --interactive=false it defaults to the first one configured.
code-request's "which account?" prompt tells accounts apart by username, so git-helper setup requires every account's username to be unique within its provider -- it'll reject a username already used by another GitHub (or GitLab) account and ask again.
git-helper setup walks through all of this interactively: it asks for each account's remote_hosts (comma-separated if the instance has more than one hostname), and only asks for api_host after you confirm that host is a real, different server rather than just a local alias.
In general, all commands can be run straight from the command-line like this:
git-helper [command]Please run with help to see more:
git-helper --helpIn addition, hopefully all these options below make working with git and Go's Git Helper more seamless.
As an additional enhancement, you can set each of the following commands to be a git plugin, meaning you can call them in a way that feels more git-native:
# Without plugins
git-helper clean-branches
git-helper code-request
# With plugins
git clean-branches
git code-requestRunning the git-helper setup command will give you the option to set plugins up. The plugin scripts are built into the binary and are written to ~/.git-helper/plugins; setup then prints how to add that directory to your PATH for your OS. On Windows it also writes git-<name>.cmd shims so the commands work from cmd.exe and PowerShell.
To make the commands even shorter, I recommend setting aliases. You can either set aliases through git itself, like this (only possible if you also use the plugin option):
git config --global alias.nb new-branchAnd then running git nb maps to git new-branch, which through the plugin, maps to git-helper new-branch.
Or you can set the alias through your shell's startup file (which is my preferred method because it can make the command even shorter, and doesn't require the plugin usage). For zsh, add lines like this to ~/.zshrc and run source ~/.zshrc:
alias gnb="git new-branch"The same line works in ~/.bashrc for bash. In fish, use abbr -a gnb git new-branch. PowerShell aliases can't take arguments, so define a function in your $PROFILE instead:
function gnb { git new-branch @args }And then, running gnb maps to git new-branch, which again routes to git-helper new-branch.
For a full list of the git aliases I prefer to use, check out my Git Aliases gist.
To set up completion (auto-filling commands as you type), run:
mkdir -p ~/.git-helper/completions
git-helper completion bash >> ~/.git-helper/completions/completion.bash
git-helper completion fish >> ~/.git-helper/completions/completion.fish
git-helper completion powershell >> ~/.git-helper/completions/completion.powershell
git-helper completion zsh >> ~/.git-helper/completions/completion.zshThen load the appropriate completion file for your scripting language to this to your shell file (e.g. load the following into your ~/.zshrc):
source ~/.git-helper/completions/completion.zshThis can be used when switching the owners of a GitHub repo. When you switch a username, GitHub only makes some changes for you. With this command, you no longer have to manually walk through each local repo and switch the remotes from each one into a remote with the new username.
This command will go through every directory in a directory, and see if it is a git directory. It will then ask the user if they wish to process the git directory in question. The command does not yet know if there's any changes to be made. If the user says 'yes', then it will check to see if the old username is included in the remote URL of that git directory. If it is, then the command will change the remote URL to instead point to the new username's remote URL. To run the command, run:
git-helper change-remote [oldOwner] [newOwner]This command will check out the default branch of whatever repository you're currently in. It looks at what branch the origin/HEAD remote is pointed to on your local machine, versus querying GitHub/GitLab for that, so if your local machine's remotes aren't up to date or aren't formatted as expected, then this command won't work as expected. To run this command, run:
git-helper checkout-defaultThis command will bring you to the repository's default branch, git pull, git fetch -p, and will clean up your local branches on your machine by seeing which ones are existing on the remote, and updating yours accordingly. To clean your local branches, run:
git-helper clean-branchesThis command can be used to handily make new GitHub/GitLab pull/merge requests from the command-line. The command uses either the GitHub REST API or GitLab API to do this, so make sure you have a ~/.git-helper/config.yml file set up in the home directory of your computer (instructions are higher in this README).
After setup is complete, you can call the command like this:
git-helper code-requestThe command will provide an autogenerated code request title based on your branch name. It will separate the branch name by '_' if underscores are in the branch, or '-' if dashes are present. Then it will join the list of words together by spaces. If there's a pattern in the form of jira-123 or jira_123 in the first part of the branch name, then it'll add JIRA-123 to the first part of the code request. In addition, the code allows setting a list of special "characters" or words that will receive unique capitalization in the title. For example:
aws=> AWSgithub=> GitHubgolang=> Golangci/cd=> CI/CD
You can configure these in your ~/.git-helper/config.yml file:
special_capitalization:
api: API
aws: AWS
cd: CD
cdn: CDN
ci: CI
cli: CLI
.
.
.If that hash isn't present in the config file, then it won't apply any special capitalization.
NOTE: If you add the special_capitalization hash to your config file and attempt to use the code-request command with any Git Helper version < 0.1.0, then the command will fail.
You can choose whether to accept this title or not. If the title's declined, you can provide your own code request title. In addition, (GitHub PR feature only) if the code notices any match of [A-Za-z]+-\d+ in the title of the code request, then it'll ask if you'd like to add a link for the first match to your PR body.
The command will also ask you if the default branch of the repository is the proper base branch to use. You can say whether that is correct or not, and if it's incorrect, you can give the command your chosen base branch.
The command will also ask you whether you'd like to mark the new code request as a draft or not.
If your project uses GitLab, the command will automatically set the merge request to delete the source branch upon merge. The value can later be changed for a specific MR either over the API or in the browser. The command also automatically sets the merge request to squash, and this will be the setting on the MR if the project allows, encourages, or requires squashing. If the project doesn't allow squashing at all, then that option will be voided, and the MR will not be squashed. Depending on the project's settings, the value can later be changed for a specific MR over the API or in the browser.
Then, it'll ask about code request templates. For GitHub, it'll ask the user to apply any pull request templates found at .github/pull_request_template.md, ./pull_request_template.md, or .github/PULL_REQUEST_TEMPLATE/*.md. Applying any template is optional, and a user can make an empty pull request if they desire. For GitLab, it'll ask the user to apply any merge request templates found at any .gitlab/merge_request_template.md, ./merge_request_template.md, or .gitlab/merge_request_templates/*.md. Applying any template is optional, and from the command's standpoint, a user can make an empty merge request if they desire (although GitLab may still add a merge request template if the project itself requires one). When searching for templates, the code ignores cases, so the file could be named with all capital letters or all lowercase letters.
For some reason, I'm always forgetting the commands to create an empty commit. So with this command, it becomes easy. The commit message of this commit will be Empty commit. To run the command, run:
git-helper empty-commitThis command will quickly and easily get rid of any local changes that are not in a commit. This command does just a git stash and git stash drop. Once you forget them, they're completely gone, so run carefully. To test it out, run:
git-helper forget-local-changesThis command is handy if you locally have a bunch of commits you wish to completely get rid of. This command basically does a hard reset to origin/HEAD. Once you forget them, they're completely gone, so run carefully. To test it out, run:
git-helper forget-local-commitsThis command is useful for making new branches in a repository on the command-line. To run the command, run:
git-helper new-branch
# OR
git-helper new-branch [optionalBranch]The command either accepts a branch name right away or it will ask you for the name of your new branch. Make sure your input does not contain any spaces or special characters.
Sets the upstream and HEAD symbolic ref to the default branch passed in:
git-helper set-head-ref [defaultBranch]See Config Setup.
See Updating Git Helper.
Show's the local version of Git Helper installed:
git-helper version- Uninstall Ruby's Git Helper:
# Uninstall the gem gem uninstall git_helper # Remove the executable which git-helper rm -rf PATH/FROM/ABOVE # Verify it's gone by this command returning command not found git-helper -v
- Install Go's Git Helper by following the instructions in
Installation - Check Go's Git Helper is installed:
git-helper version
- Run the setup command (optional for Beta modes < 1.0.0, required otherwise):
git-helper setup
- Move forward with your day!
To submit a feature request, bug ticket, etc, please submit an official GitHub issue. To copy or make changes, please fork this repository. When/if you'd like to contribute back to this upstream, please create a pull request on this repository.
Please follow included Issue Template(s) and Pull Request Template(s) when creating issues or pull requests.
To report any security vulnerabilities, please view this repository's Security Policy.
For information on licensing, please see LICENSE.md.
When interacting with this repository, please follow Contributor Covenant's Code of Conduct.
To make a new release:
- Merge the pull request via the big green button
- Trigger a new workflow from GitHub Actions and pass in the next sensible semantic version (including the
vprefix). GoReleaser builds and publishes the binaries indicated in thegoreleaser.yamlfile andchecksums.txt