38leinaD / bpmn-diff

A Git difftool for BPMN-files

A Git difftool for BPMN-files

bpmn-diff allows visual diffing of BPMN-files from the command-line. It can also easily be integrated as a difftool for Git.

Note that this tool is only possible due to the awesome bpmn-js-diffing library (see here for the online version). At it’s core, this is a repackaging/embeeded version of the library.

The application-shell is based on Quarkus and thus can also be built into a Native Executable with GraalVM.

Usage

Go to Releases and download the executable version for your environment (Linux, Mac or Windows).

Usage of native executable

Make sure that the file is executable:

chmod u+x bpmn-diff-0.0.1-linux

If you have cloned this repo, you can find example BPMN files under <repo>/bpmn-diff-webapp/resources. We can compare them with:

./bpmn-diff-0.0.1-linux <repo>/bpmn-diff-webapp/resources/pizza-collaboration/old.bpmn <repo>/bpmn-diff-webapp/resources/pizza-collaboration/new.bpmn

You cannot just diff individual files but also perform a diff on folders:

./bpmn-diff-0.0.1-linux <repo>/bpmn-diff/src/test/resources/diffs/dir-diff/a <repo>/bpmn-diff/src/test/resources/diffs/dir-diff/b

Usage of JAR

Make sure that you have Java 11 or above installed by running:

java -version

If you have cloned this repo, you can find example BPMN files under <repo>/bpmn-diff-webapp/resources. We can compare them with:

java -jar bpmn-diff-0.0.1.jar <repo>/bpmn-diff-webapp/resources/pizza-collaboration/old.bpmn <repo>/bpmn-diff-webapp/resources/pizza-collaboration/new.bpmn

You cannot just diff individual files but also perform a diff on folders:

java -jar bpmn-diff-0.0.1.jar <repo>/bpmn-diff/src/test/resources/diffs/dir-diff/a <repo>/bpmn-diff/src/test/resources/diffs/dir-diff/b

Usage as Git difftool

Add the following to your .gitconfig

[difftool "bpmn"]
    cmd = java -jar <full-path-to-repo>/bpmn-diff-0.0.1.jar $LOCAL $REMOTE
    trustExitCode = false

Commands

Assuming you have a Git repository with some BPMN-files, here are some useful commands:

Diff on flow.bpmn between latest and previous commit:

git difftool -t bpmn HEAD~1 HEAD flow.bpmn

If you run above command without the filename, it will do a diff for the whole commit. This means, the difftool will be invoked for each file one after the other. This is not very useful as you will have to inspect each BPMN file one after the other and the difftool will also be invoked for changes in files that are not BPMN-files. For this reason, there is --dir-diff which is also supported by this tool:

git difftool --dir-diff -t bpmn HEAD~1 HEAD

This will open a pane to switch between files.

Build

To build the project you need Java 8 or above.

git clone https://github.com/38leinaD/bpmn-diff.git
cd bpmn-diff
./gradlew quarkusBuild --uber-jar

The built bpmn-diff-999-SNAPSHOT-runner.jar is found under bpmn-diff/build .

You can find example BPMN files under bpmn-diff-webapp/resources. We can compare them with:

java -jar bpmn-diff-999-SNAPSHOT.jar ./bpmn-diff-webapp/resources/pizza-collaboration/old.bpmn ./bpmn-diff-webapp/resources/pizza-collaboration/new.bpmn

A browser window should open up showing the application. On close of the browser window, the application is terminated. As the application does not ship with it’s own browser, it tries to find a browser on the local system. The steps, and how to set a specific browser, are outlined under Browser Detection.

You cannot just diff individual files but also perform a diff on folders:

java -jar bpmn-diff/build/bpmn-diff-999-SNAPSHOT-runner.jar ./bpmn-diff/src/test/resources/diffs/dir-diff/a ./bpmn-diff/src/test/resources/diffs/dir-diff/b

Native Executable

To build a native executable you either need to have GraalVM installed or Docker.

If you have GraalVM installed and have set the GRAALVM_HOME environment variable, run:

./gradlew buildNative

This is the only option for Windows users and will require an installation of Visual Studio.

If you are in a linux-based environment and have Docker installed, you may also build a native executable by running:

./gradlew buildNative --docker-build=true

Browser Detection

The tool opens the difftool in a browser installed on your system. By default the BestFit strategy is used which will try to detect an appropriate browser in the following way:

1. If the environment variable BROWSER_COMMAND is defined, run this with the URL of the webapp as parameter.

2. If the executable google-chrome is detected on your PATH, use this executable.

3. If the executable firefox is detected on your PATH, use this executable.

4. Else, ask the operating system to use the default browser.

Other strategies can be selected via the command-line flag -browser=. Values are BestFit, Chrome, Firefox, System. System will try to use whatever browser is configured by the operating system.

TODO: Testing has been done with Linux only. So, setting Chrome or`Firefox` might fail on windows as it only checks if specifically named executables are found on the PATH.