Installation
- Git: See Git compatibility.
-
Rust: Install from https://rustup.rs. You can check your current Rust version, if any, by running
rustup show.
Step 1 of 3. You can install 'git-branchless` via many package managers:
Caution
The Windows build appears to trigger a bug in Git for Windows (see #370 Running under PowerShell fails to invoke git in hooks). It's recommended to use WSL instead.
Otherwise, install git-branchless with Cargo:
$ cargo install --locked git-branchless
If you would prefer to install the latest development version, you can instead run cargo install --git https://github.com/arxanas/git-branchless git-branchless. For more information on using development versions of git-branchless, see the Runbook.
Step 2 of 3. Each Git repository needs to be opted into git-branchless. To do so, go to the repository and then run git branchless init. The output should look similar to this:
$ cd my/git/repo
$ git branchless init
Created config file at /Users/dkelkhoff/git/coldtrack/Infoplus-Scripts/.git/branchless/config
Auto-detected your main branch as: main
If this is incorrect, run: git branchless init --main-branch <branch>
Installing hooks: post-applypatch, post-checkout, post-commit, post-merge, post-rewrite, pre-auto-gc, reference-transaction
Successfully installed git-branchless.
To uninstall, run: git branchless init --uninstall
Confirm installation: git-branchless should now be set up for your repository. To confirm that it works, run git sl. It should produce output like this:
⋮
◆ b2c57ae3 9m (master) docs: add README.md
Step 3 of 3 (recommended, but not required): Add an alias from git to git-branchless wrap to your shell resource file. For example:
$ echo >> ~/.bashrc "alias git='git-branchless wrap --'"
This will improve the git undo experience considerably, as it will be able to group more logically-related events.
If git checkout -b <TAB> doesn't show your branch names, you can restore completions by using a script here: https://github.com/arxanas/git-branchless/discussions/217#discussioncomment-4875866
To learn more about using git-branchless, visit the Tutorial. Or feel free to start a discussion.
It would also be appreciated if you filled out the user survey!
Q: Running cargo install --git https://github.com/arxanas/git-branchless produces this error message:
$ cargo install --git https://github.com/arxanas/git-branchless
Updating git repository `https://github.com/arxanas/git-branchless`
Installing git-branchless v0.3.12 (https://github.com/arxanas/git-branchless?branch=arxanas/sync#e3ccc646)
Updating crates.io index
error: failed to select a version for the requirement `libgit2-sys = "^0.14.0"`
candidate versions found which didn't match: 0.13.2+1.4.2, 0.13.1+1.4.2, 0.13.0+1.4.1, ...
location searched: crates.io index
required by package `git2 v0.15.0`
... which satisfies dependency `git2 = "^0.15.0"` (locked to 0.15.0) of package `git-branchless-lib v0.3.12 (/Users/mleewilliams/.cargo/git/checkouts/git-branchless-f6bbbe393421e02f/e3ccc64/git-branchless-lib)`
... which satisfies path dependency `lib` (locked to 0.3.12) of package `git-branchless v0.3.12 (/Users/mleewilliams/.cargo/git/checkouts/git-branchless-f6bbbe393421e02f/e3ccc64/git-branchless)`
A: Your version of cargo is too old to resolve dependencies properly. Try upgrading your rustc version to at least 1.60. See #476 for more details.
Q: Running git branchless init produces this error message:
$ git branchless init
git: 'branchless' is not a git command. See 'git --help'.
A: Ensure that git-branchless is on your PATH. Since it was installed with cargo, you should see an entry for .cargo/bin on your PATH. For example:
$ echo "$PATH"
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/wkhan/.local/bin:/Users/wkhan/.cargo/bin
If it's not present, try re-installing Rust from https://rustup.rs.
Q: Running git branchless init produces this error message:
$ git branchless init
dyld[63457]: missing symbol called
error: git-branchless died of signal 6
A: You may be using an old version of rustc on an M1 Mac. If so, try upgrading your rustc version to at least 1.57. See #254 for more details.