Warning

This ruleset is under active development. The API is subject to breaking changes before a v1 release.

Bazel rules for GNU diffutils

GNU diffutils provides diff, cmp, diff3, and sdiff.

This project provides rules that run these programs as Bazel actions.

By default, the project registers toolchains for prebuilt binaries as diffutils only does source releases. You may alternatively register your own toolchain based on a source build of the diffutils BCR entry (see example).

Documentation

To install, follow instructions from the release you wish to use.

See the docs folder for rule documentation and examples.

Use cases

Create different types of patches

load("@diff.bzl", "diff")

diff(
    name = "patch"
    args = ["--unified"],
    srcs = ["a.txt", "b.txt"],
    patch = "a.patch"
)

Compare binary files

load("@diff.bzl", "cmp")

cmp(
    name = "compare_bins",
    args = ["--bytes", "4", "--verbose"],
    srcs = ["bin_a", "bin_b"],
    out = "cmp_output"
)

Produce human-readable diffs

# Side-by-side diff
load("@diff.bzl", "sdiff")

sdiff(
    name = "side_by_side",
    srcs = ["a.txt", "b.txt"],
    out = "compare"
)

# Three way diff
load("@diff.bzl", "diff3")

sdiff(
    name = "three_way_diff",
    srcs = ["my.txt", "old.txt", "yours.txt"],
    out = "compare"
)

Keep generated sources up to date

Pass validate = 1 to cmp or diff to create a build validation error when a generated source input diverges from the output tree file.

load("@diff.bzl", "diff")

diff(
    name = "foo",
    srcs = [
      "foo.pb.go",
      ":foo_generated",
    ],
    validate = 1
)

An error message with command to run to patch the file will be output.

ERROR: diff command exited with non-zero status.

To accept the diff, run:
(cd $(bazel info workspace); patch -p0 < bazel-out/k8-fastbuild/bin/foo.patch)

This also works for directories.

To validate all diff, cmp, etc. actions by default, set common --@diff.bzl//diff:validate=true in your bazelrc.

Support automatic patch workflows

This ruleset outputs patches for source tree files into the diff_bzl__patch output group by default, making it easier to collect and apply patches in an automated fashion. See the build & patch example script.

The output groups for source patches can be customized via the source_patch_output_groups attribute. This can be used to categorize types of patches. For example, diff targets with source_patch_output_groups = ["autopatch"] might identify patches that should automatically be applied if the build fails on CI, whereas a "snapshot_test" group could identify patches that require human review, etc.

diff(
    name = "foo",
    srcs = [
      "foo.pb.go",
      ":foo_generated",
    ],
    validate = 1,
    source_patch_output_groups = ["autopatch"],
)

NB: Only patches for files in the source tree are placed in the above output group(s). Patches for files in the output tree are not included as they should not be modified outside of Bazel.