Add the beginnings of a Diff Tool layer.

Review Request #12599 — Created Sept. 14, 2022 and submitted — Latest diff uploaded




We've used GNU Diff as a standard dependency for many of our SCMs for
many years now, as it's been readily available (either built-in or easy
to install) on all target systems for ages. However, that is changing
with the upcoming macOS Ventura release, which will replace GNU Diff
with Apple Diff, a fork of some unknown version of BSD Diff.

To prepare for that, and to provide an opportunity for cleaning up any
code dealing with raw diffs, this change introduces a new module. This provides abstractions around invoking
diff tools and creating a normalized representation of results.

These will eventually be used in place of any execute() or
run_process() call around diff.

To start, this change adds the abstract base class, BaseDiffTool, and
a results class, DiffFileResult.

BaseDiffTool subclasses must set a couple of attributes:

  • diff_tool_id: A unique string for registration and identification.
  • name: A human-readable name for the diff tool (used for

And implement some methods:

  • check_available(): Checks for presence/compatibility of the wrapped
    diff tool.
  • run_diff_file(): Runs the diff tool for two files, converting the
    provided flags to command line arguments, and returning a normalized
    diff result.
  • get_install_instructions(): Optional, but is used for error messages
    if no diff tool can be found.

Results of a run_diff_file() are represented by a DiffFileResult
object. This wraps a result byte stream that can be used by the caller,
along with some utility methods for getting the original/modified
headers or hunk data in different forms. This also contains state on
whether it diffed a binary file or a text file and whether there were

Currently, nothing uses this, and GNU Diff support isn't available.
Upcoming changes will flesh this out, providing a diff tool registry,
GNU diff support, SCMClient integration, and finally, Apple Diff

Unit tests pass.

Tested these with some upcoming changes and verified this functionality

Built the docs and checked for obvious errors.