Have you ever tried comparing unformatted JSON?

Why Diffing Single-Line JSON Files is a Headache

If you’ve ever tried to compare two JSON files in a typical diff tool, you’ve probably run into an annoying problem: everything looks like a mess. Many JSON files – especially those generated by APIs or build processes – are stored as a single, massive line of text. While this might be efficient for machines, it’s a nightmare for humans trying to spot differences.

Here’s why diffing single-line JSON files is so frustrating:

  1. It’s Impossible to Read – When JSON is crammed into one long line, even a small change is buried somewhere in a sea of text. You end up scrolling sideways, trying to spot tiny variations.

  2. The Entire Line Lights Up – Standard diff tools work line by line. Since the entire JSON file is one line, even a minor tweak—like a changed number or an added key—makes the whole thing show up as different, offering no clue about what actually changed.

  3. Whitespace Confusion – Some diff tools highlight even trivial whitespace changes, making the diff unnecessarily noisy and harder to interpret.

  4. No Structural Awareness – Typical text-based diff tools don’t understand JSON’s nested structure. A small change deep inside an object is just as hard to spot as a top-level change.

The Fix: Formatting JSON Before Diffing

One way to make JSON diffs readable is by prettifying the JSON before comparing it. This ensures changes are easy to spot, with each key-value pair on its own line. We can use Git’s textconv feature with SmartGit to enable pre-processing, making diffs much more readable and useful.

This approach is designed for binary files like PDFs, but we can also leverage it to format text files for better diffing—exactly what we’ll explain here.

For detailed documentation on Git’s textconv capabilities, refer to the official documentation:
Git Attributes: Performing Text Diffs of Binary Files

Note: Depending on the runtime of the conversion tools, rendering the diff in SmartGit may take a moment.

How to configure Git textconv for JSON Files with SmartGit

1. Update .gitattributes

To apply this filter to all .json files in your repository, add the following line to your .gitattributes file:

*.json diff=json

This ensures Git recognizes JSON files and applies the json diff filter when running git diff.

2. Configure Git to Use textconv

Next, define a Git text conversion filter for JSON files. Open your global or repository-level Git config file (~/.gitconfig or .git/config). This tells Git to use our script whenever it diffs JSON files.

Using Phyton

When you have a machine with Phyton installed and the Phyton Script directory correctly set up in your PATH environment then this is probably the best version.

[diff "json"]
    textconv = python -m json.tool

Using PowerShell

[diff "json"]
    textconv = pwsh -c "& { param([string]$fileName) $data = Get-Content -Path $fileName; $data | ConvertFrom-Json | ConvertTo-Json -Depth 100 }"

Using Bash

To format JSON using the Bash the best way is to install “jq” and restart so the jq command is available everywhere in your shell/system (https://jqlang.org/download/)

[diff "json"]
    textconv = bash -c 'jq . \"$0\" -'

Using textconv in SmartGit

Once configured, SmartGit will automatically apply the textconv filter when diffing JSON files, displaying formatted, structured diffs instead of hard-to-read single-line files.

Conclusion

By using textconv, we can significantly improve JSON diffing in SmartGit, making changes clearer and easier to review. This setup not only enhances readability but also streamlines the development workflow when working with JSON-based configurations, API responses, or structured data files.

Would you like additional troubleshooting tips or alternative methods for JSON diffing?

Example Repository

We created an example repo on GitHub that also shows how to leverage textconv for other file types like PDF, Docx, XLSX for diffing with SmartGit.

https://github.com/syntevosmartgit/textconv