Installation

• Prerequisites
• Installation
• Next steps
• Troubleshooting
  • error: failed to select a requirement libgit2-sys = "..."
  • git: 'branchless' is not a git command
  • dyld: missing symbol called

Prerequisites

• Git: See Git compatibility.
• Rust: Install from https://rustup.rs. You can check your current Rust version, if any, by running rustup show.

Installation

NOTE: due to https://github.com/arxanas/git-branchless/issues/127, you must install with the --locked flag for cargo.

Step 1 of 3. 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 --locked --git https://github.com/arxanas/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
Installing hook: post-commit
Installing hook: post-rewrite
Installing hook: post-checkout
Installing alias (non-global): git smartlog
Installing alias (non-global): git sl
Installing alias (non-global): git hide
Installing alias (non-global): git unhide
Installing alias (non-global): git prev
Installing alias (non-global): git next
Installing alias (non-global): git restack
Installing alias (non-global): git undo

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.

Next steps

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!

Troubleshooting

error: failed to select a requirement libgit2-sys = "..."

Q: Running cargo install --locked --git https://github.com/arxanas/git-branchless produces this error message:

$ cargo install --locked --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.

git: 'branchless' is not a git command

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.

dyld: missing symbol called

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.