Skip to content
kain88-de edited this page May 4, 2024 · 129 revisions

Prerequisites

Installation

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.

Packaging status

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

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 --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.

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.

Clone this wiki locally