Add the beginnings of a Diff Tool layer.

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

Information

RBTools
release-4.x

Reviewers

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

Summary ID
Add the beginnings of a Diff Tool layer.
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 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 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.
e3fde7d9fecf3d739a5275901d5d37d2bcd4c761
Description From Last Updated

Add a Version Added: here.

maubinmaubin

Add a Version Added: here.

maubinmaubin

There's a 0 here that can be taken out.

maubinmaubin

Missing a period at the end of this sentence. Maybe it could also use some info on what the default …

maubinmaubin

Typo: speek -> speed

maubinmaubin
david
  1. Ship It!
  2. 
      
maubin
  1. 
      
  2. Show all issues

    Add a Version Added: here.

  3. Show all issues

    Add a Version Added: here.

  4. Show all issues

    There's a 0 here that can be taken out.

  5. Show all issues

    Typo: speek -> speed

  6. 
      
chipx86
chipx86
chipx86
maubin
  1. 
      
  2. rbtools/diffs/tools/base/diff_file_result.py (Diff revisions 1 - 4)
     
     
    Show all issues

    Missing a period at the end of this sentence. Maybe it could also use some info on what the default regex pattern is.

  3. 
      
chipx86
maubin
  1. Ship It!
  2. 
      
chipx86
david
  1. Ship It!
  2. 
      
chipx86
Review request changed
Status:
Completed
Change Summary:
Pushed to release-4.x (c3a724d)