[][documentation] [][website] [][demo]

DiffDetective - Variability-Aware Source Code Differencing

DiffDetective is an open-source Java library for variability-aware source code differencing and the analysis of version histories of software product lines. This means that DiffDetective can turn a generic differencer into a variability-aware differencer by means of a pre- or post-processing. DiffDetective is centered around formally verified data structures for variability (variation trees) and variability-aware diffs (variation diffs). These data structures are generic, and DiffDetective currently implements C preprocessor support to parse respective annotations when used to implement variability. The picture below depicts the process of variability-aware differencing.

Given two states of a C-preprocessor annotated source code file (left), for example before and after a commit, DiffDetective constructs a variability-aware diff (right) that distinguishes changes to source code from changes to variability annotations. DiffDetective can construct such a variation diff either, by first using a generic differencer, and separating the information (center path), or by first parsing both input versions to an abstract representation, a variation tree (center top and bottom), and constructing a variation diff using a tree differencing algorithm in a second step.

Additionally, DiffDetective offers a flexible framework for large-scale empirical analyses of git version histories of statically configurable software. In multiple studies, DiffDetective was successfully employed to study the commit histories of up to 44 open-source git repositories, including the Linux Kernel, GCC, Vim, Emacs, or the Godot game engine.

Setup

DiffDetective is a Java Maven library. While DiffDetective depends on some custom libraries (FeatureIDE library, Sat4j, Functjonal) these are prepackaged with DiffDetective. So all you need is Java ≥16 and Maven or alternatively Nix. In the following, we explain the setup with Java and Maven, as well as via Nix.

Cloning the Repository

Clone this repository and navigate inside it:

git clone https://github.com/VariantSync/DiffDetective
cd DiffDetective

In case you are using Nix Flakes, you may skip cloning the repository.

Building and Installing

You can build and install DiffDetective with Maven such that it can be used in your own project. Alternatively, you can use a jar which includes all necessary dependencies. Such a jar can either be built manually using Maven or using Nix.

Building and Installing With Maven

First, Maven needs to be installed. Either provide it yourself (e.g., using a system package manager or on Windows, download from their website) or, if you have Nix installed, run nix-shell (stable Nix) or nix develop (Nix Flakes) to provide all necessary build tools.

Next, build DiffDetective and install it on your system so that you can access it from your own projects:

mvn install

To add DiffDetective as a dependency to your own project, add the following snippet to the pom.xml of your Maven project, but make sure to pick the right version number. The current version number can be obtained by running scripts/version.sh

<dependency>
    <groupId>org.variantsync</groupId>
    <artifactId>DiffDetective</artifactId>
    <version>2.3.0</version>
</dependency>

If you prefer to just use a jar file, you can find a jar file with all dependencies at DiffDetective/target/diffdetective-2.3.0-jar-with-dependencies.jar (again, the version number might be different). You can (re-)produce this jar file by either running mvn package or mvn install within you local clone of DiffDetective.

Disclaimer: Setup tested with maven version 3.6.3.

Building with Nix

Alternatively to manually building using Maven, Nix can be used. Both a flake.nix and a default.nix are provided. Hence, you can build DiffDetective using

nix-build # stable version
# or
nix build # Flake version

In case you are using Nix Flakes, you can skip cloning the repository as usual: nix build github:VariantSync/DiffDetective#.

Afterward, the result symlink points to the Javadoc, a DiffDetective jar for use as a library, a self contained DiffDetective jar with all dependencies included and a simple script for executing a DiffDetective main class provided as argument (e.g., evaluations used in previous research, see below under 'Publications').

How to Get Started

For a demonstration on how to get started using the library, we have prepared a demo repository [here][demo]. You may clone it as a template and example for including the library into your own projects. Additionally, there is a screencast available on YouTube, guiding you through the demo's setup and source code:

Supported Differencing Algorithms

In principle, any generic differencing algorithm (i.e, any algorithm that may operate on text or trees) can be made variability-aware with DiffDetective, as explained in our demo paper (see below). Some algorithms are integrated directly in the DiffDetective library, while others come as additional Maven projects.

Shipped with DiffDetective

Git Diff as implemented by JGit
GumTree, and all algorithms and matching engines supported by the GumTree library

Extra Modules

TrueDiff: Support for TrueDiff comes as a separate Maven project.

Publications

Variability-Aware Differencing with DiffDetective (FSE 2024, ⭐ Best Demo Paper ⭐)

[][screencast] [][demo]

P. M. Bittner, A. Schultheiß, B. Moosherr, T. Kehrer, T. Thüm. Variability-Aware Differencing with DiffDetective. Demonstrations at International Conference on the Foundations of Software Engineering 2024, ACM, New York, NY, July 2024

This paper gives an overview of DiffDetective, its design, features, use-cases, and past case studies. We recommend reading this paper if you are interested in the design of DiffDetective or if you consider using it for your own projects or research. The paper is accompanied by a [demo project][demo] as well as a [screencast][screencast] (also see How to Get Started above).

Classifying Edits to Variability in Source Code (ESEC/FSE 2022)

P. M. Bittner, C.Tinnes, A. Schultheiß, S. Viegener, T. Kehrer, T. Thüm. Classifying Edits to Variability in Source Code. In Proceedings of the 30th ACM Joint European Software Engineering Conference and Symposium on the Foundations of Software Engineering (ESEC/FSE 2022), ACM, New York, NY, November 2022

<img padding="10" align="right" src="https://www.acm.org/binaries/content/gallery/acm/publications/artifact-review-v1_1-badges/ar

DiffDetective

Install / Use

README