Diffing and Promotion¶
(diff <file1> <file2>) is very similar to
(run diff <file1>
<file2>). In particular it behaves in the same way:
<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-commandcommand line argument. Note that it’s only called when the files are not byte equals
By default, it will use
patdiffif it is installed.
patdiffis 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.
(diff a b)is a built-in action, Dune knows that
bare 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
<file1>doesn’t exist, it will compare with the empty file.
It allows promotion. See below.
(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
Whenever an action
(diff <file1> <file2>) or
<file2>) fails because the two files are different, Dune allows
you to promote
<file1> is a source
<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)))
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.
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.
dune promote. This will copy the generated
data.expecteddirectly in the source tree.
You can also use
dune runtest --auto-promote, which will
automatically do the promotion.