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
rbtools.diffs.tools
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 arounddiff
.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
errors/logging).
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
changes.
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
support.
Unit tests pass.
Tested these with some upcoming changes and verified this functionality
works.Built the docs and checked for obvious errors.