Runbook - arxanas/git-branchless Wiki

Releasing

To release a new version:

Testing

Running tests locally

Run tests with cargo test. The tests depend on the version of Git you're using, so you need to provide a Git executable as an environment variable with the PATH_TO_GIT variable. For example:

$ PATH_TO_GIT=$(which git) cargo test  # use globally-installed version
$ PATH_TO_GIT=/path/to/dir/git cargo test  # use the `git` executable inside /path/to/dir

Run the linter with cargo clippy -- -D warnings (see https://github.com/rust-lang/rust-clippy for installation instructions).

Run the formatter with rustfmt, or through your editor.

Updating tests

The project uses cargo-insta for snapshot testing. You can download the command-line utility with cargo install cargo-insta to make it easier to update test cases when the output changes:

Running tests in CI

Tests will automatically run in Github Actions when you open a pull request against the repository. These include various versions of Git on Linux, as well as on Windows.

Some builds only run later, for performance reasons:

Profiling

With tracing

git-branchless uses the tracing library for profiling. Only functions which are annotated with #[instrument] and explicitly-created span!s are captured in the traces. Learn more...

You can produce a profile by running a git-branchless command by setting certain environment variables:

For example:

$ RUST_PROFILE=foo.json cargo run -C /path/to/repo smartlog
...
$ git status
HEAD detached at f08491d
Untracked files:
  (use "git add <file>..." to include in what will be committed)
        foo.json-0

Since git-branchless sometimes invokes itself in a subprocess (via Git hook), the nesting level is tracked internally, and you may see files of the form foo.json-0, foo.json-1, etc.

The produced profiles can be imported into chrome://tracing (on Google Chrome) or https://ui.perfetto.dev/ (all browsers).

With cargo-flamegraph

You can use cargo flamegraph to produce flamegraphs using a system profiler (perf on Linux or dtrace elsewhere). This is a relatively polished and low-configuration setup. In particular, it can be useful if you want to examine performance using a sampling rather than tracing method:

Note for macOS users: System Integrity Protection may require that you run cargo flamegraph as root, i.e. with sudo. Otherwise, dtrace may fail to attach to the process.

Supported Git versions

See the compatibility matrix at https://github.com/arxanas/git-branchless/wiki/Git-compatibility. For now, git-branchless is committed to supporting Git v2.24 and later, where reasonable.

Note that the reference-transaction hook is only supported from Git v2.29 and later. This means that some tests will have different behavior in older versions of Git. Many tests check to see if reference transactions are supported before proceeding, e.g.

if !git.supports_reference_transactions()? {
    return Ok(());
}