> ## Documentation Index
> Fetch the complete documentation index at: https://mehen.ophi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# mehen diff

> Compare metrics between two git revisions and emit a per-file delta report as JSON or GitHub-flavored Markdown.

`mehen diff` compares metrics between two git revisions and emits a per-file delta report. It is the
engine behind the [GitHub Action](/guides/github-action) and the recommended way to wire mehen into a
PR workflow.

```text theme={null}
mehen diff [OPTIONS]
```

| Flag                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--from <FROM>`                       | Base revision to compare from.                                                                                                                                                                                                                                                                                                                                                                                  |
| `--to <TO>`                           | Head revision to compare to.                                                                                                                                                                                                                                                                                                                                                                                    |
| `-p, --paths <PATHS>...`              | Repository-relative files or directories to compare.                                                                                                                                                                                                                                                                                                                                                            |
| `-M, --metrics <METRICS>`             | Comma-separated metrics. When omitted, defaults are resolved **per file language**: source-code files use `cyclomatic,cognitive,nom.functions,loc.lloc,mi.visual_studio`; SQL files use `sql.change_risk_score,sql.maintainability_index,sql.review_burden_index,sql.cognitive_complexity,sql.loc.code`. An explicit list applies to every file. Prefix with `+` for higher-is-better, `-` for lower-is-better. |
| `-I, --include <INCLUDE>...`          | Glob to include files.                                                                                                                                                                                                                                                                                                                                                                                          |
| `-X, --exclude <EXCLUDE>...`          | Glob to exclude files.                                                                                                                                                                                                                                                                                                                                                                                          |
| `-O, --output-format <OUTPUT_FORMAT>` | `markdown` or `json`.                                                                                                                                                                                                                                                                                                                                                                                           |
| `--show-unchanged`                    | Show files where every metric is unchanged.                                                                                                                                                                                                                                                                                                                                                                     |
| `--ignore-generated[=<BOOL>]`         | Skip files marked `linguist-generated` (default `true`).                                                                                                                                                                                                                                                                                                                                                        |
| `--fail-on <FAIL_ON>`                 | Exit non-zero when named thresholds are crossed. Comma-separated: `dmi-drop`, `new-broken-link`, `filler-high`, `all`.                                                                                                                                                                                                                                                                                          |

## Examples

<Tabs>
  <Tab title="PR head vs main (Markdown)">
    ```bash theme={null}
    mehen diff --from main --to HEAD --paths src --output-format markdown
    ```
  </Tab>

  <Tab title="JSON for a CI script">
    ```bash theme={null}
    mehen diff --from "$BASE_SHA" --to "$HEAD_SHA" --paths . \
               --output-format json > metrics-diff.json
    ```
  </Tab>

  <Tab title="Custom metrics + polarity">
    ```bash theme={null}
    mehen diff --from main --to HEAD --paths src \
               --metrics "+mi.visual_studio,-cognitive,-loc.lloc"
    ```
  </Tab>

  <Tab title="Strict gate on docs">
    ```bash theme={null}
    mehen diff --from main --to HEAD --paths docs \
               --fail-on dmi-drop,new-broken-link,filler-high
    ```
  </Tab>
</Tabs>

## Output formats

<Tabs>
  <Tab title="Markdown">
    GitHub-flavored Markdown table optimized for sticky PR comments. This is what the
    [GitHub Action](/guides/github-action) posts on each PR.
  </Tab>

  <Tab title="JSON">
    Per-file deltas with both old and new values for every metric. Designed to be parsed by CI scripts
    that want their own threshold logic.
  </Tab>
</Tabs>

## What gets compared

mehen runs the equivalent of `mehen metrics` against each side, joins by repository-relative path, and
computes per-metric deltas. Files that exist on only one side are reported as new or deleted. Files
matched by `linguist-generated` are skipped by default.

When no `--metrics` are given, a mixed pull request (e.g. both `.ts` and `.sql`
files) produces a single table whose columns are the union of each language's
default metrics. Every row populates only the columns its analyzer publishes;
columns from another language render as `–`. This keeps SQL changes visible in
the default GitHub Action path — without it, SQL files would be measured only
against source-code metrics they never emit and silently drop out as unchanged.

## `--fail-on` thresholds

`--fail-on` accepts a comma-separated list of band-crossing rule IDs:

| Rule              | Triggers when…                                                                          |
| ----------------- | --------------------------------------------------------------------------------------- |
| `dmi-drop`        | A Markdown file's [DMI](/metrics/markdown/dmi) crosses a band downward.                 |
| `new-broken-link` | At least one new broken link is added.                                                  |
| `filler-high`     | A Markdown file's [Filler / Lazy Risk](/metrics/markdown/filler-lazy-risk) is `≥ 0.60`. |
| `all`             | Any of the above.                                                                       |

The rules align with the severity-1 / severity-2 indicators on the
[PR comment design](/guides/pr-comment-design) page.

For per-metric numeric gating (e.g. "fail if cyclomatic delta > 5"), use the
[GitHub Action's `thresholds` input](/guides/github-action), which post-processes the JSON report.
See [Concepts → Thresholds and diffs](/concepts/thresholds-and-diffs).

## Exit codes

| Code | Meaning                                               |
| ---- | ----------------------------------------------------- |
| 0    | Success — the comment is advisory.                    |
| 1    | IO, git, parser-fatal, or unsupported-language error. |
| 2    | One or more `--fail-on` rules crossed (gating exit).  |

## See also

* [GitHub Action](/guides/github-action) — runs `mehen diff` for you and posts the report on PRs.
* [PR comment design](/guides/pr-comment-design) — Markdown comment template.
* [Concepts → Thresholds and diffs](/concepts/thresholds-and-diffs).