Add --check-diff to meson format, to show what should be formatted

3 files changed, 26 insertions, 3 deletions

diff --git a/docs/markdown/Commands.md b/docs/markdown/Commands.md
index 09d8fd95f..339dd93b7 100644
--- a/docs/markdown/Commands.md
+++ b/docs/markdown/Commands.md
@@ -496,6 +496,9 @@ or `--inline` arguments.
 *Since 1.9.0* Using `-` as source file with `--editor-config` now requires
 `--source-file-path` argument to ensure consistent results.
 
+*Since 1.10.0* When `--check-diff` is specified, instead of silently exiting
+with an error code, `meson format` will print a diff of the formatting changes.
+
 
 #### Differences with `muon fmt`
 
diff --git a/docs/markdown/snippets/format-check-diff-option.md b/docs/markdown/snippets/format-check-diff-option.md
new file mode 100644
index 000000000..efcab4f89
--- /dev/null
+++ b/docs/markdown/snippets/format-check-diff-option.md
@@ -0,0 +1,8 @@
+## `meson format` has a new `--check-diff` option
+
+When using `meson format --check-only` to verify formatting in CI, it would
+previously silently exit with an error code if the code was not formatted
+correctly.
+
+A new `--check-diff` option has been added which will instead print a diff of
+the required changes and then exit with an error code.
diff --git a/mesonbuild/mformat.py b/mesonbuild/mformat.py
index ac36dc08b..0281ed532 100644
--- a/mesonbuild/mformat.py
+++ b/mesonbuild/mformat.py
@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import difflib
 import re
 import typing as T
 from configparser import ConfigParser, MissingSectionHeaderError, ParsingError
@@ -996,7 +997,13 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
     inplace_group.add_argument(
         '-q', '--check-only',
         action='store_true',
-        help='exit with 1 if files would be modified by meson format'
+        help='silently exit with 1 if files would be modified by meson format'
+    )
+    inplace_group.add_argument(
+        '-d', '--check-diff',
+        action='store_true',
+        default=False,
+        help='exit with 1 and show diff if files would be modified by meson format'
     )
     inplace_group.add_argument(
         '-i', '--inplace',
@@ -1092,9 +1099,14 @@ def run(options: argparse.Namespace) -> int:
                     sf.write(formatted)
             except IOError as e:
                 raise MesonException(f'Unable to write to {src_file}') from e
-        elif options.check_only:
-            # TODO: add verbose output showing diffs
+        elif options.check_only or options.check_diff:
             if code != formatted:
+                if options.check_diff:
+                    diff = difflib.unified_diff(code.splitlines(), formatted.splitlines(),
+                                                str(src_file), str(src_file),
+                                                '(original)', '(reformatted)',
+                                                lineterm='')
+                    print('\n'.join(diff))
                 return 1
         elif options.output:
             try: