Add --diff option for outputting diffs of formatting changes. #12598

Osmose · 2022-04-06T02:44:18Z

Description

Adds a new --diff flag that is similar to --check and --list-different, but instead of listing filenames, it outputs unified diffs with the changes Prettier would have made to format the file.

This was first requested in #6885 and there isn't really a firm answer one way or another from a maintainer yet, but I figure having a PR to look at could help move the discussion forward.

Thank you!

Checklist

I’ve added tests to confirm my change works.
- This probably isn't enough testing but I had trouble finding good examples of how --check and --list-different are tested so any pointers to examples to mimick would be welcome.
(If changing the API or CLI) I’ve documented the changes I’ve made (in the docs/ directory).
(If the change is user-facing) I’ve added my changes to changelog_unreleased/*/XXXX.md file following changelog_unreleased/TEMPLATE.md.
I’ve read the contributing guidelines.

✨Try the playground for this PR✨

fisker · 2022-04-06T17:26:42Z

What's your opinion on #11833

Osmose · 2022-04-06T23:46:36Z

What's your opinion on #11833

If there was, like, a diff reporter available somehow, that would solve the need of having diff output somewhere, but IMO it's not terribly ergonomic. --diff is about adding new information that prettier currently isn't exposing, while reporters are more about different formats for information that already is made available (and to me that feels not in scope for prettier). That's just my personal take, of course.

Osmose · 2022-06-02T22:31:41Z

Just checking in, anything I can do to help move this along?

Osmose · 2023-03-01T19:15:55Z

@fisker Hiiii, checking in again, anything besides fixing the merge conflicts I can do to help move this along? Thanks!

fisker · 2023-03-02T01:19:32Z

tests/integration/__tests__/diff.js

+  runPrettier("cli/with-shebang", ["--diff", "--parser", "babel"], {
+    input: "0",
+  }).test({
+    stdout: outdent({ trimTrailingNewline: false })`


Let's not assert this, but make a snapshot. (Remove stdout)

fisker · 2023-03-02T01:21:24Z

tests/integration/__tests__/diff.js

+    "cli/write",
+    ["--diff", "formatted.js", "unformatted.js"],
+    {
+      stdoutIsTTY: true,


tty test seems unnecessary.

fisker · 2023-03-02T01:23:44Z

src/cli/index.js

+    [context.argv.check, context.argv.listDifferent, context.argv.diff].filter(
+      (o) => o
+    ).length > 1


Suggested change

[context.argv.check, context.argv.listDifferent, context.argv.diff].filter(

(o) => o

).length > 1

[context.argv.check, context.argv.listDifferent, context.argv.diff].filter(

Boolean

).length > 1

fisker · 2023-03-02T01:24:55Z

tests/integration/__tests__/diff.js

+  test("Should be the same", async () => {
+    expect(await result0.stdout).toEqual(await result1.stdout);
+  });
+});


Can you add a test for stdin format/check?

fisker · 2023-03-02T01:26:59Z

changelog_unreleased/cli/12598.md

+<!--
+
+1. Choose a folder based on which language your PR is for.
+
+   - For JavaScript, choose `javascript/` etc.
+   - For TypeScript specific syntax, choose `typescript/`.
+   - If your PR applies to multiple languages, such as TypeScript/Flow, choose one folder and mention which languages it applies to.
+
+2. In your chosen folder, create a file with your PR number: `XXXX.md`. For example: `typescript/6728.md`.
+
+3. Copy the content below and paste it in your new file.
+
+4. Fill in a title, the PR number and your user name.
+
+5. Optionally write a description. Many times it’s enough with just sample code.
+
+6. Change ```jsx to your language. For example, ```yaml.
+
+7. Change the `// Input` and `// Prettier` comments to the comment syntax of your language. For example, `# Input`.
+
+8. Choose some nice input example code. Paste it along with the output before and after your PR.
+
+-->
+
+#### Add --diff option for outputting diffs of formatting changes. (#12598 by @Osmose)


Suggested change



#### Add --diff option for outputting diffs of formatting changes. (#12598 by @Osmose)

#### Add --diff option for outputting diffs of formatting changes (#12598 by @Osmose)

fisker · 2023-03-02T01:29:55Z

docs/cli.md

@@ -124,6 +124,14 @@ prettier --single-quote --list-different "src/**/*.js"

 You can also use [`--check`](cli.md#--check) flag, which works the same way as `--list-different`, but also prints a human-friendly summary message to stdout.

+## `--diff`


I prefer --diff only work when doing --check

prettier --check --diff .

WDYT?

My only thought against it would be that if anyone wanted to pipe the output to a diff file that could be applied later by a diff tool, requiring --check would mean that they have to strip the summary (unless you mean adding --diff would implicitly remove the summary).

But I don't really feel strongly about it and am fine either way.

My only thought against it would be that if anyone wanted to pipe the output to a diff file that could be applied later by a diff tool

Make sense.

How about:

For files

prettier . --diff

Format and show diff

prettier . --write --diff

Not allow.

prettier . --check --diff

Format and show diff

For stdin

echo "code" | prettier --diff

Format and show diff

echo "code" | prettier --write --diff

Not allow.

echo "code" | prettier --check --diff

Format and show diff.

So --diff always do the same as --check, but show different message, and it can use together with --check, but not --write.

Osmose · 2023-03-23T03:17:15Z

Updated based on feedback:

--check can be used with --diff but doesn't change it's behavior (i.e. it won't output the extra summary output that --check normally does).
Now throws an error if --write is used with --diff.
Removed the tty tests, output assertions, and added tests for the new behavior.
Rebased on main.

@fisker Thanks for the review, lemme know if anything else needs fixing!

DV8FromTheWorld · 2023-09-08T16:15:06Z

Besides the conflicts, is there anything holding this back? We'd love to use this

george-gca · 2024-01-22T15:41:12Z

@fisker can we do anything to have this issue prioritized, or at least reviewed?

oalders · 2024-02-13T16:23:14Z

Any progress on this?

gregmarr · 2024-05-22T21:30:41Z

src/cli/index.js

+    ).length > 1
+  ) {
+    throw new Error(
+      "Cannot use --check, --list-different, or --diff together."


Seems like this would be sufficient:

if ((context.argv.check || context.argv.diff) && context.argv.listDifferent) { throw new error("Cannot use --list-different with --check or --diff"); }

LoganDark · 2024-06-25T13:25:41Z

@oalders is this PR still being worked on?

oalders · 2024-06-25T16:32:36Z

@LoganDark I have no idea. I'm interested in seeing this get done, but I haven't been working on it. Maybe you meant to ping someone else?

LoganDark · 2024-06-25T16:36:08Z

I have no idea. I'm interested in seeing this get done, but I haven't been working on it. Maybe you meant to ping someone else?

oops, meant to ping the author. sorry (I'm sure they've already been notified by now of course)

Osmose · 2024-06-25T16:45:33Z

I have no idea. I'm interested in seeing this get done, but I haven't been working on it. Maybe you meant to ping someone else?

oops, meant to ping the author. sorry (I'm sure they've already been notified by now of course)

This is waiting on having someone with merge powers to review it, I'll always be ready to rebase it once it's clear that it will be reviewed again.

LoganDark · 2024-06-25T16:47:57Z

This is waiting on having someone with merge powers to review it, I'll always be ready to rebase it once it's clear that it will be reviewed again.

It looks like there's already an unaddressed review comment? #12598 (comment)

Osmose · 2024-06-25T17:30:51Z

gregmarr isn't part of the Prettier org and wouldn't be able to merge the PR.

pfraces-rc · 2024-08-30T14:23:30Z

@fisker what can we do to move this forward?

george-gca · 2024-08-30T15:00:33Z

The best solution I found so far is the one I commented in #6885 (comment).

pfraces-rc · 2024-08-30T15:04:49Z

The best solution I found so far is the one I commented in #6885 (comment).

I have that in mind for sure, but I also want this feature for my local environment.

lydell · 2024-09-09T17:13:35Z

I tried out this branch a little bit. Here are some things I noticed:

I was surprised the output does not have color, like git diff. The whole point of the option is to help humans understand what changes need to be done to fix the formatting. Color helps a lot in diffs. Note that GitHub Actions supports terminal colors in its logs.
I think that getting CI failures due to wrong newlines is somewhat common, due to Windows - Line endings & conversion actions/checkout#135 and Prettier’s end of line option defaulting to auto. Currently, --diff prints the entire file with - followed by the entire file again with + when you have the wrong newlines, and the output does not make it clear that the newlines are wrong in any way.
If you leave trailing spaces on a line, the diff shows that line with - followed by the same line with +, but the trailing spaces are not visible in any way so it’s unclear why there was a diff.
If you put a non-breaking space instead of a space by mistake, the diff does not show this.
If you indent with tabs instead of spaces, that can be difficult to spot in diffs as well, depending on how wide your terminal renders tabs and your number of spaces in the tab width option.
The output says Index: test.js. I have no idea what “Index:” means here.
When running with both --diff and --check, it looks like the --check flag is simply ignored – I would have expected the output from both diff and check to be printed.
When running with both --diff and --list-different, the error message is [error] Cannot use --check, --list-different, or --diff together., but it looks like the PR does allow --check and --diff together on purpose.
Can anyone link to discussion where it was decided to go with a --diff flag, rather than just adding a diff to --check always?

It probably makes sense to test black, gofmt, dprint and biome, and take inspiration from them.

Osmose · 2025-03-06T07:35:39Z

Sorry, I missed the message last year, thanks for the feedback.

However, I don't really have interest in following up with that much feedback after two and a half years of little meaningful engagement from maintainers, so I'm gonna close this and someone else can work off of that if they want to.

masalomon mentioned this pull request Apr 28, 2022

Add diff in output of --check (for CI use cases) #6885

Open

fisker self-requested a review March 2, 2023 00:06

fisker reviewed Mar 2, 2023

View reviewed changes

Osmose added 4 commits March 22, 2023 17:29

Add --diff option for outputting diffs of formatting changes.

84a2103

Add changelog entry for --diff.

3bce521

Fix typo.

a9799a6

Allow using --check with --diff and disallow --diff with --write.

613c4b2

Osmose force-pushed the diff branch from 0df68c3 to 613c4b2 Compare March 23, 2023 03:08

Osmose requested a review from fisker March 23, 2023 03:17

gregmarr reviewed May 22, 2024

View reviewed changes

prettier locked and limited conversation to collaborators Mar 6, 2025

prettier unlocked this conversation Mar 6, 2025

Osmose closed this Mar 6, 2025

		@@ -124,6 +124,14 @@ prettier --single-quote --list-different "src/*/.js"

		You can also use [`--check`](cli.md#--check) flag, which works the same way as `--list-different`, but also prints a human-friendly summary message to stdout.

		## `--diff`

Uh oh!

Add --diff option for outputting diffs of formatting changes. #12598

Add --diff option for outputting diffs of formatting changes. #12598

Uh oh!

Conversation

Osmose commented Apr 6, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

fisker commented Apr 6, 2022

Uh oh!

Osmose commented Apr 6, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Osmose commented Jun 2, 2022

Uh oh!

Osmose commented Mar 1, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fisker Mar 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fisker Mar 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Osmose commented Mar 23, 2023

Uh oh!

DV8FromTheWorld commented Sep 8, 2023

Uh oh!

george-gca commented Jan 22, 2024

Uh oh!

oalders commented Feb 13, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LoganDark commented Jun 25, 2024

Uh oh!

oalders commented Jun 25, 2024

Uh oh!

LoganDark commented Jun 25, 2024

Uh oh!

Osmose commented Jun 25, 2024

Uh oh!

LoganDark commented Jun 25, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Osmose commented Jun 25, 2024

Uh oh!

pfraces-rc commented Aug 30, 2024

Uh oh!

george-gca commented Aug 30, 2024

Uh oh!

pfraces-rc commented Aug 30, 2024

Uh oh!

lydell commented Sep 9, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Osmose commented Mar 6, 2025

Uh oh!

Uh oh!

Osmose commented Apr 6, 2022 •

edited

Loading

Osmose commented Apr 6, 2022 •

edited

Loading

fisker Mar 2, 2023 •

edited

Loading

fisker Mar 2, 2023 •

edited

Loading

LoganDark commented Jun 25, 2024 •

edited

Loading

lydell commented Sep 9, 2024 •

edited

Loading