# git-toolbelt: practical Git commands for scripts and daily use

> git-toolbelt adds individual Git commands for branch discovery, worktree navigation, change inspection, status checks, and common recovery operations. It suits Unix-shell users who want compact output and script-friendly exit codes, but it does not replace Git itself.

**nvie/git-toolbelt** — A suite of useful Git commands that aid with scripting or every day command line usage

- Repository: https://github.com/nvie/git-toolbelt
- Stars: 1,419 · Forks: 123
- Language: Shell
- License: BSD-3-Clause
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/nvie-git-toolbelt

## Why git-toolbelt extends Git rather than replacing it

git-toolbelt addresses a specific friction point in Git command-line work: many useful Git operations still require remembering compound commands, filtering their output, or interpreting detailed status reports. The suite is aimed at people who use Git throughout the day and at developers writing shell scripts. Its commands keep the normal `git` command namespace, so examples such as `git current-branch`, `git modified`, and `git is-clean` read like extensions to the existing command rather than a separate application.

The repository contains separate executable files named after these commands. Based on the repository layout, each helper is a POSIX shell script that delegates work to Git and related command-line utilities. This makes the project a collection of small interfaces, not a single long-running service. There is no configuration service, daemon, database, or application UI documented in the README.

The suite divides its commands by purpose. Everyday commands cover branch selection, changed files, local commits, updates, diffs, and work-on operations. Novice-oriented commands handle destructive cleanup, stashing, publishing, and undo operations. Scripting commands focus on answering repository questions through output or exit status. Advanced commands include changing commit placement or dates, splitting commits, and manipulating skipped changes. This organization identifies the intended level of experience and the expected interaction style.

This is a wrapper collection with a specific opinion about Git's interface. Some commands save typing. Others suppress details that `git status` normally prints, which matters when a file list is going directly into an editor or another program. The wrappers still depend on standard Git concepts and do not introduce a different repository model.

## Compact output and exit codes for git-toolbelt automation

The scripting interface is based on small predicates and list commands. The README states that commands such as `git-is-repo`, `git-is-headless`, `git-is-clean`, `git-is-dirty`, `git-local-branch-exists`, `git-remote-branch-exists`, and `git-tag-exists` typically return exit codes without producing output. That design is intended for shell conditions rather than human-facing reports. git-toolbelt also provides machine-processable branch lists, including local, remote, and active branches.

The everyday commands deliberately reduce Git output. `git modified` returns locally modified files without the detailed status columns from `git status`, and it never includes non-existing files. Passing `-i` includes modified files that are already staged. Paths passed after `--` restrict the result, which makes the command suitable for operations such as opening only the files relevant to a directory.

Branch metadata receives similar treatment. `git current-branch` returns the current branch name when there is one. `git main-branch` probes for local branches named `main` or `master` because the README states that there is no reliable way to detect a repository's default branch name in every case. That choice is convenient, but it establishes a clear boundary: a repository whose primary branch uses another name may not produce the result a script expects.

For commit identifiers, `git sha` returns the SHA of a specified object or the current branch head when no object is supplied. The `-s` option shown in the README shortens that output. These commands favor parsable values and concise output, although the README does not promise a formal machine-readable format such as JSON.

## Installing git-toolbelt with Homebrew or source links

Homebrew is the documented package installation route. The following commands add nvie's tap and install the suite:

```bash
brew tap nvie/tap
brew install nvie/tap/git-toolbelt
```

After Homebrew completes, the Git subcommands should be available through the installation path configured by the package manager. Without Homebrew, the README requires GNU coreutils for `realpath`.

For a clone-based developer installation, link every command into a directory already on `PATH`:

```bash
git clone https://github.com/nvie/git-toolbelt.git
cd git-toolbelt
make link
```

`make link` selects `~/.local/bin` or `~/bin`, whichever is already present on `PATH`; if neither is present, the Makefile's candidate order makes `~/.local/bin` the fallback. The target creates symbolic links rather than copied files, so edits to the checkout take effect immediately. That is useful during development, but it also means moving or deleting the clone breaks those links.

The installation prefix can be set explicitly when another location is required:

```bash
make link PREFIX=~/opt/bin
```

Remove linked commands with:

```bash
make unlink
```

The documented platform boundary is strict. These are POSIX shell scripts and require a Unix shell. On Windows, the README directs users to Git for Windows with Git Bash or WSL. The scripts will not run in native PowerShell.

## A first git-toolbelt session with branches and modified files

Begin inside a Git repository and ask for the current branch:

```bash
git current-branch
```

The README's example returns `main`. A repository in detached `HEAD` state does not have a current branch, and `git is-headless` is available for testing that condition.

Next, inspect files changed in the working tree:

```bash
git modified
```

Unlike `git status`, the result is a plain list and omits non-existing files. To include staged modifications, add `-i`:

```bash
git modified -i
```

Limit the output to a path with the standard pathspec separator:

```bash
git modified -- src/
```

The pathspec is relative to the current directory. This behavior allows the same command to be used from a subdirectory without first calculating repository-relative names.

To inspect work accumulated since `main`, use:

```bash
git modified-since
```

For a direct diff against `main`, the README gives `git diff-since`. It also accepts a specified branch or commit, so workflows based on a differently named integration branch can pass that reference explicitly.

One practical publishing command is `git push-current`. It pushes the current branch to `origin` and configures tracking, corresponding to `git push -u origin <current-branch>`. README options are forwarded, which means the documented invocation `git push-current -f` requests a force-push. This is a consequential operation, and the README shows no interactive confirmation step.

## git-toolbelt branch surgery and recovery commands

Several helpers wrap common branch operations that would otherwise be longer Git command sequences. `git fixup` and `git fixup-with` target commit cleanup, while `git workon` is included among the everyday branch commands. The README does not document every argument accepted by these commands, so their exact option sets should be checked in the corresponding script before use in automation.

`git spinoff` has a more specific purpose. According to the README, it creates and checks out a new branch at the current branch, makes that new branch track the current branch, and resets it to the last commit shared with the upstream. This supports extracting feature work after development has already started on another branch. If the current branch has no upstream, or it has no commits that need extraction, the command still creates the branch and leaves the previous branch untouched.

The recovery commands address operations in which repository history or working-tree state may change. `git-drop-local-changes`, `git-stash-everything`, `git-undo-commit`, and `git-undo-merge` fall into that category. The advanced `git-trash` command also appears in the repository layout, although the README does not explain its interface. git-toolbelt offers the commands, but it does not replace understanding how Git stores work and history.

`git-edit-author-dates` and `git-sync-commit-date` are also present as repository-level commands. The README confirms their existence but does not provide enough argument detail to construct safe examples. Their presence makes the suite broader than read-only branch queries, but scripts should check the individual command source or built-in help before passing arguments.

## Platform, branch-name, and state-changing limits

The clearest limitation is platform support. Because the project consists of POSIX shell scripts, native PowerShell cannot execute it. WSL and Git Bash provide Unix-like environments on Windows, but the README does not claim that every Windows path or shell integration is identical to a Unix workstation. Users also need Git available because the helpers occupy Git's command namespace.

The `main` and `master` probe is another constraint. The README states that the default branch cannot be identified reliably in every repository, so `git main-branch` checks those two local names and returns the first one found. This is predictable for repositories using `main` or `master`, but it can misrepresent repositories that use another primary branch or have both names locally. Automation should prefer an explicit ref when the branch name matters.

The suite is not a state monitor. Scripting commands provide point-in-time answers through output or exit codes. They do not wait for remote updates, retry network operations, or expose documented JSON. Remote-branch behavior also depends on the local view of remotes. The README says `git remote-branches` can filter by a specific remote, but it does not state that the command fetches fresh remote state first.

Several helpers change repository state. `git push-current -f` is explicitly documented, while drop, stash, undo, and commit-splitting commands operate on local state or history. The README states no compatibility guarantee for arbitrary combinations of pending rebases, unresolved conflicts, worktrees, or unusual Git configurations. The safer boundary is to inspect `git status`, the current branch, and relevant history before running a state-changing helper.

## How git-toolbelt differs from direct Git and editor tooling

The real alternative is to use Git's built-in commands, aliases, and status parsers directly. Direct Git offers the same underlying repository operations without adding a separate command suite. In many cases, a short alias can cover a frequently used compound command. The difference is that git-toolbelt packages several opinionated behaviors as ordinary `git-*` executables, including terse file lists, predicates designed around exit codes, and workflows such as `git spinoff` and `git modified-since`.

A graphical Git client is another alternative when the priority is visual review rather than composable command lines. The README does not describe compatibility with any particular editor or graphical client, so no integration should be assumed. A client may expose history and conflict state through an interface, while git-toolbelt is built for terminal execution and shell conditionals.

For automation, the distinction between default Git and git-toolbelt is partly presentation and convenience. Git can print branches, changes, and commit IDs already, but scripts may need additional filtering or stable conventions. git-toolbelt reduces that work for its documented cases. It does not provide a general query language, a remote synchronization service, or a documented guarantee that every output format remains stable across releases.

This makes git-toolbelt a good fit for people who accept its conventions and want discoverable commands. It is a poor fit for users who require native PowerShell support, strict JSON interfaces, or a completely independent abstraction from Git's current command semantics.

## License, maintenance, and source-linked upgrade costs

The project is distributed under `BSD-3-Clause`. The repository includes a `LICENSE` file. This identifies the license terms, but repository consumers remain responsible for following applicable notices and obligations rather than relying on a project review as legal advice.

Maintenance is recent. The last push was on 2026-09-24. Releases include `v1.12.0` on 2026-09-08, `v1.11.0` on 2026-05-21, and `v1.10.0` on 2026-02-12. These dates show recent project changes, but the README does not provide a compatibility policy or a migration guide for each release.

A Homebrew installation delegates updates to the package workflow. A clone-based `make link` installation reduces upgrade effort because the commands are symlinks into the checkout, but it also makes updates part of maintaining that Git repository. Pulling a new revision into the checkout changes the scripts resolved through those links. Moving or deleting the source directory breaks the installation.

The `make unlink` target removes the links. The README does not document a migration tool for converting a source-linked setup into a package-managed installation. Adopters choosing the clone workflow must account for the lifecycle of that directory rather than treating `make link` as a conventional copied installation. A shell hash cache may also need to recognize moved command paths, although the Makefile prints its own PATH warning when the probe command does not resolve as intended.

## Conclusion

Adopt git-toolbelt if your work includes repeated Git queries, shell automation, or recovery commands and you use Bash, Git Bash, WSL, or another Unix shell. Do not adopt it for native PowerShell use or as a substitute for learning Git's underlying commands. Before installing, verify that your command directory is on PATH, that `realpath` is available when Homebrew is not used, and whether the `main` or `master` detection rule fits your repositories.

## FAQ

### How do I install nvie/git-toolbelt?

The README documents Homebrew installation through `brew tap nvie/tap` followed by `brew install nvie/tap/git-toolbelt`. A clone-based installation uses `make link`, which creates command symlinks in `~/.local/bin` or `~/bin` when one is already on `PATH`.

### Does nvie/git-toolbelt run in native PowerShell?

No. The project consists of POSIX shell scripts and does not run in native PowerShell. On Windows, the README directs users to Git for Windows with Git Bash or WSL.

### Why does git-toolbelt's main-branch command not always find the repository default branch?

The README says `git main-branch` probes for local branches named `main` or `master` because the default branch cannot be identified reliably in every repository. It returns the first branch found, so repositories using another primary branch name are outside its documented detection rule.

## Sources

- [Issues](https://github.com/nvie/git-toolbelt/issues)
- [License: BSD-3-Clause](https://github.com/nvie/git-toolbelt/blob/main/LICENSE)
- [nvie/git-toolbelt on GitHub](https://github.com/nvie/git-toolbelt)
- [README](https://github.com/nvie/git-toolbelt/blob/main/README.md)
- [Releases](https://github.com/nvie/git-toolbelt/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nvie-git-toolbelt