Diffing and Promotion

(diff <file1> <file2>) is very similar to (run diff <file1> <file2>). In particular it behaves in the same way:

  • When <file1> and <file2> are equal, it does nothing.

  • When they are not, the differences are shown and the action fails.

However, it is different for the following reason:

  • The exact command used for diff files can be configured via the --diff-command command line argument. Note that it’s only called when the files are not byte equals

  • By default, it will use patdiff if it is installed. patdiff is a better diffing program. You can install it via opam with:

    $ opam install patdiff
    
  • On Windows, both (diff a b) and (diff? a b) normalize end-of-line characters before comparing the files.

  • Since (diff a b) is a built-in action, Dune knows that a and b are needed, so you don’t need to specify them explicitly as dependencies.

  • You can use (diff? a b) after a command that might or might not produce b, for cases where commands optionally produce a corrected file

  • If <file1> doesn’t exist, it will compare with the empty file.

  • It allows promotion. See below.

Note that (cmp a b) does no end-of-line normalization and doesn’t print a diff when the files differ. cmp is meant to be used with binary files.

Promotion

Whenever an action (diff <file1> <file2>) or (diff?  <file1> <file2>) fails because the two files are different, Dune allows you to promote <file2> as <file1> if <file1> is a source file and <file2> is a generated file.

More precisely, let’s consider the following Dune file:

(rule
 (with-stdout-to data.out (run ./test.exe)))

(rule
 (alias   runtest)
 (action (diff data.expected data.out)))

Where data.expected is a file committed in the source repository. You can use the following workflow to update your test:

  • Update the code of your test.

  • Run dune runtest. The diff action will fail and a diff will be printed.

  • Check the diff to make sure it’s what you expect. This diff can be displayed again by running dune promotion diff.

  • Run dune promote. This will copy the generated data.out file to data.expected directly in the source tree.

You can also use dune runtest --auto-promote, which will automatically do the promotion.