project: compare: add -f/--format for machine-readable output

Mirror the format-string interface of "west list" on "west compare":
when --format is given, print one line per dirty project using the
format string, and skip the banner/status output. Reuses the
format_project() helper extracted in the previous commit, so all
"west list --format" keys ({name}, {url}, {path}, {abspath},
{posixpath}, {revision}, {sha}, {groups}, etc.) work identically.

Signed-off-by: YvesLL <toyears@hotmail.com>

Author: yvesll

src/west/app/project.py

@@ -863,13 +863,38 @@ def __init__(self):
             The command also prints output for the manifest repository if it
             has nonempty status.
 
-            The output is meant to be human-readable, and may change. It is
-            not a stable interface to write scripts against. This command
-            requires git 2.22 or later.'''),
+            The default output is meant to be human-readable, and may change.
+            It is not a stable interface to write scripts against. If you need
+            machine-readable output (e.g. to feed back into "west update" or
+            "west forall"), pass --format; see FORMAT STRINGS below.
+
+            This command requires git 2.22 or later.'''),
         )
 
     def do_add_parser(self, parser_adder):
-        parser = self._parser(parser_adder, epilog=ACTIVE_CLONED_PROJECTS_HELP)
+        parser = self._parser(
+            parser_adder,
+            epilog=f'''\
+{ACTIVE_CLONED_PROJECTS_HELP}
+
+FORMAT STRINGS
+--------------
+
+When --format is given, "west compare" prints one line per project
+with changes, rendered using the given Python format string. The
+supported keys are the same ones documented in "west list --help".
+Unlike the default output, --format output is a stable interface
+suitable for scripting, for example:
+
+POSIX:
+
+    west compare --format '{{name}}' | while read -r name; do west update "$name"; done
+
+PowerShell:
+
+    west compare --format '{{name}}' | ForEach-Object {{ west update $_ }}
+''',
+        )
         parser.add_argument(
             'projects',
             metavar='PROJECT',
@@ -900,6 +925,13 @@ def do_add_parser(self, parser_adder):
                     or any compare.ignore-branches configuration
                     option''',
         )
+        parser.add_argument(
+            '-f',
+            '--format',
+            help='''if given, print one line per project with changes
+                    using this format string (stable, machine-readable
+                    output); see FORMAT STRINGS below''',
+        )
         return parser
 
     def do_run(self, args, ignored):
@@ -915,14 +947,21 @@ def do_run(self, args, ignored):
 
         failed = []
         printed_output = False
+
+        def compare_project(project, fmt):
+            if fmt is None:
+                self.compare(project)
+            else:
+                self._format_project(project, fmt)
+
         for project in self._cloned_projects(args, only_active=not args.all):
             if isinstance(project, ManifestProject):
                 # West doesn't track the relationship between the manifest
                 # repository and any remote, but users are still interested
                 # in printing output for comparisons that makes sense.
                 if self._has_nonempty_status(project):
                     try:
-                        self.compare(project)
+                        compare_project(project, args.format)
                         printed_output = True
                     except subprocess.CalledProcessError:
                         failed.append(project)
@@ -960,7 +999,7 @@ def has_checked_out_branch(project):
                 ):
                     continue
 
-                self.compare(project)
+                compare_project(project, args.format)
                 printed_output = True
             except subprocess.CalledProcessError:
                 failed.append(project)

tests/test_project.py

@@ -628,6 +628,122 @@ def test_compare(config_tmpdir, west_init_tmpdir):
     assert 'mybranch' in cmd('compare --no-ignore-branches')
 
 
+def test_compare_format_manifest(config_tmpdir, west_init_tmpdir):
+    # ManifestProject special-casing: empty output, single-line
+    # machine-readable output without any banner, and the path/sha/url
+    # keys that are distinct from regular projects -- same conventions
+    # as 'west list'.
+
+    # No dirty projects -> no output at all.
+    assert cmd('compare --format {name}') == ''
+
+    # Dirty the manifest repo.
+    foo = west_init_tmpdir / 'zephyr' / 'foo'
+    with open(foo, 'w'):
+        pass
+
+    # The whole point of --format is stable machine-readable output:
+    # no banner ('=== ...'), exactly one line per dirty project, and
+    # the ManifestProject is named 'manifest' just like 'west list'.
+    out = cmd('compare --format {name}')
+    assert '===' not in out
+    assert out.splitlines() == ['manifest']
+
+    # Path-style keys for the ManifestProject come from manifest.repo_*,
+    # not project.*. {sha}/{url} are 'N/A' and {revision} is 'HEAD'.
+    # {groups} is empty. These all match 'west list' behavior.
+    assert cmd('compare -f {path}').strip() == 'zephyr'
+    assert cmd('compare -f {abspath}').strip() == str(west_init_tmpdir / 'zephyr')
+    assert cmd('compare -f {posixpath}').strip() == (Path(west_init_tmpdir / 'zephyr').as_posix())
+    assert cmd('compare -f {sha}').strip() == 'N/A'
+    assert cmd('compare -f {url}').strip() == 'N/A'
+    assert cmd('compare -f {revision}').strip() == 'HEAD'
+    assert cmd(['compare', '-f', '[{groups}]']).strip() == '[]'
+
+    # --exit-code still fires when --format produced any output.
+    with pytest.raises(SystemExit):
+        cmd('compare --exit-code --format {name}')
+
+    # Cleanup -> empty output again.
+    os.unlink(foo)
+    assert cmd('compare --format {name}') == ''
+
+
+def test_compare_format_projects(config_tmpdir, west_init_tmpdir):
+    # Regular (non-manifest) projects: every format key, multi-project
+    # ordering, and interactions with --all / named projects / the
+    # manifest.group-filter configuration option.
+
+    cmd('update')
+    kconfiglib = west_init_tmpdir / 'subdir' / 'Kconfiglib'
+    bar = kconfiglib / 'bar'
+    with open(bar, 'w'):
+        pass
+
+    # {sha} must resolve to a real 40-char hex SHA for a cloned project
+    # (not 'N/A'): this verifies DelayFormat actually gets invoked when
+    # the format string references {sha}.
+    line = cmd(['compare', '-f', '{name}|{sha}']).strip()
+    name, sha = line.split('|')
+    assert name == 'Kconfiglib'
+    assert re.match(r'^[0-9a-f]{40}$', sha)
+
+    # All remaining keys.
+    out = cmd([
+        'compare',
+        '-f',
+        '{name}|{url}|{path}|{abspath}|{posixpath}|{revision}|{groups}',
+    ]).strip()
+    fields = out.split('|')
+    assert fields[0] == 'Kconfiglib'
+    assert fields[1].endswith('/Kconfiglib')  # url from test fixture's url-base
+    # {path} preserves the manifest YAML value verbatim (always forward
+    # slashes), regardless of OS -- same behavior as 'west list -f {path}'.
+    assert fields[2] == 'subdir/Kconfiglib'
+    assert fields[3] == str(kconfiglib)
+    assert fields[4] == Path(kconfiglib).as_posix()
+    assert fields[5] == 'zephyr'
+    assert fields[6] == 'Kconfiglib-group'  # set in test fixture's manifest
+
+    # Multiple dirty projects produce one line per project, in manifest
+    # order (Kconfiglib before tagged_repo in this fixture's manifest).
+    tagged = west_init_tmpdir / 'tagged_repo' / 'baz'
+    with open(tagged, 'w'):
+        pass
+    assert cmd('compare -f {name}').splitlines() == ['Kconfiglib', 'tagged_repo']
+    os.unlink(tagged)
+
+    # An inactive project is skipped by default but appears with --all
+    # or when named explicitly (same active-project semantics as plain
+    # 'west compare').
+    cmd('config manifest.group-filter -- -Kconfiglib-group')
+    assert cmd('compare -f {name}') == ''
+    assert cmd('compare --all -f {name}').strip() == 'Kconfiglib'
+    assert cmd('compare -f {name} Kconfiglib').strip() == 'Kconfiglib'
+    cmd('config -d manifest.group-filter')
+
+    os.unlink(bar)
+
+
+def test_compare_format_errors(config_tmpdir, west_init_tmpdir):
+    # Malformed format strings must fail cleanly via self.die() ->
+    # SystemExit, not with an uncaught KeyError/IndexError traceback.
+    # Dirty the manifest repo so the format path is actually reached.
+    foo = west_init_tmpdir / 'zephyr' / 'foo'
+    with open(foo, 'w'):
+        pass
+
+    # Unknown named key.
+    with pytest.raises(SystemExit):
+        cmd('compare -f {bogus}')
+
+    # Positional argument (fmt.format() has no positional args).
+    with pytest.raises(SystemExit):
+        cmd('compare -f {0}')
+
+    os.unlink(foo)
+
+
 def test_diff(west_init_tmpdir):
     # FIXME: Check output