differ

README

Differ 🔎 ↔ 🔍

Differ is a robust Go codebase comparison tool that enables you to easily identify relevant changes across codebases at a per-struct, per-function, and per-method level. With Differ, you can focus on the changes that matter and ignore the rest.

✨ Highlights

• ⚡ Swiftly compare symbols* between two codebases, unaffected by differences in package paths or file names.
• 🔗 Automatically identifies corresponding symbols* by parsing Go code with go/ast.
• 🙈 Ignore changes considered irrelevant or approved.

* symbol: the name of a function, struct or method (symbol for methods are <type>.<method>)

⚙ Installation

Quickly

Just go install and you're good to go!

go install github.com/bloxapp/ssv/scripts/differ@latest

Tip: you can replace @latest with @any-git-branch.

Locally

After cloning the SSV repo, just go install from it.

cd ./scripts/differ
go install .

🚀 Usage

Usage: differ <left> <right>

Arguments:
  <left>     Path to the left codebase.
  <right>    Path to the right codebase.

Flags:
  -h, --help                    Show context-sensitive help.
      --config="config.yaml"    Path to the config file.
      --output="output.diff"    Path to the output diff file.

Example:

differ ./ssv ./ssv-spec

👀 Reviewing

Differ provides a web UI to review the changes.

1. Copy & paste the contents of output.diff into differ.vercel.app (or your local instance — see below)
2. Approve changes
3. Copy from Change IDs at the top
4. Edit config.yaml and append the IDs to ApprovedChanges

Locally Running the UI

After cloning the repo, install & run the Next.js project:

cd ./scripts/differ/ui
npm install
npm run dev

Check it out at http://localhost:3000

Configuration

The config.yaml file is used to fine-tune the behavior of Differ.

# List of approved change IDs to ignore.
ApprovedChanges: []

# Identifiers to ignore during comparison.
IgnoredIdentifiers:
  - logger

# Package names that should be reduced to their last component.
ReducedPackageNames:
  - ssv
  - qbft

# Pairs of packages to compare across the codebases.
Comparisons:
  - Packages:
      Left:
        - ./protocol/v2/ssv/runner
      Right:
        - ./ssv
    # User-defined hints for symbol matching. Maps from Left to Right.
    Hints:
      ReconstructSignature: PartialSigContainer.ReconstructSignature

  - Packages:
      Left:
        - protocol/v2/qbft/controller
        - protocol/v2/qbft/instance
      Right:
        - ./qbft