Sort JSON Keys to Eliminate Merge Conflicts and Clean Up Git Diffs

If your team has merge conflicts in package.json, requirements.txt, or JSON config files at least once a month, the fix is sorting. Unsorted dependency lists collect new entries at the bottom of the object, so two parallel pull requests that each add a package hit the exact same line and produce a conflict. Sorted lists put each new entry at its alphabetical position — conflicts only happen when the same dependency is added twice, which is rare.

This post covers the pattern, how to enforce it team-wide, and how our browser sorter fits in for ad-hoc cleanups.

Why Unsorted JSON Creates Merge Conflicts

Git's merge algorithm compares lines. When two branches both change the same line, Git cannot decide which change wins and flags it as a conflict.

In a typical package.json, the last line before the closing brace of the dependencies object is whatever package was added most recently. When branch A adds "axios" and branch B adds "zod" in parallel, both commits modify the same line region — the tail of the dependencies object. Git sees two competing changes and produces a conflict.

With alphabetically sorted dependencies, "axios" goes near the top and "zod" goes near the bottom. They occupy different line regions, and Git merges them automatically.

The same problem affects tsconfig.json, settings.json, Terraform locals, Ansible vars, and any JSON where a team adds entries over time.

The Noisy Diff Problem

Even when there is no merge conflict, unsorted JSON produces noisy diffs. Imagine two reviewers:

Reviewer 1 opens a PR that adds three new dependencies. The diff shows three additions at the bottom of the dependencies object. Easy to scan.

Reviewer 2 opens a PR where a tool auto-formatted package.json and re-ordered the keys. The diff shows every dependency "moved." The real change (maybe a version bump) is buried in 40 lines of position churn.

If the team had alphabetical sorting enforced, Reviewer 2's PR would only show the actual version bump. The position noise disappears because sorted order is deterministic regardless of who added the dependency or when.

This matters for code review speed: reviewers trust sorted files more because the diff is trustworthy. Unsorted files erode review attention over time.

The Sort-Before-Committing Workflow

For an existing repo that has never sorted its JSON, the cleanup is a one-time operation:

Step 1. Open your package.json (or other config). Copy the full contents.

Step 2. Paste into our JSON Key Sorter. Ensure recursive is checked.

Step 3. Click Sort. Copy the output back into the file.

Step 4. Commit as "chore: alphabetize package.json". This is a pure formatting commit — no logic change.

Step 5. After merge, every future change to the file gets the clean-diff benefit.

For teams of 3+ developers working on the same repo, the one-time cleanup is worth it within a month. For solo projects, the benefit is smaller but still positive for your future self diffing against old versions.

Sell Custom Apparel — We Handle Printing & Free Shipping

Enforcing Sort Team-Wide With Prettier

Manual sorting gets skipped under deadline pressure. Automate with Prettier + sort plugin:

npm install -D prettier prettier-plugin-sort-json
# .prettierrc
{
  "plugins": ["prettier-plugin-sort-json"],
  "jsonRecursiveSort": true
}

Pair with lint-staged so every commit that touches JSON gets sorted automatically:

// package.json
{
  "lint-staged": {
    "*.json": "prettier --write"
  }
}

Plus Husky for the pre-commit hook:

npm install -D husky
npx husky install
npx husky add .husky/pre-commit "npx lint-staged"

Now every commit that modifies JSON produces alphabetically sorted output, regardless of which developer made the change or which editor they use. Merge conflicts in dependency lists effectively disappear.

Sort-and-Compare — The Debug Workflow

When two environments return different JSON and you need to know what actually changed:

Step 1. Grab both JSON payloads (staging vs production, two tenants, two API versions).

Step 2. Sort each independently with our JSON Key Sorter, recursive mode on.

Step 3. Paste both into our diff checker or side-by-side code diff.

Step 4. The diff now shows only real value differences — added fields, removed fields, changed values. No "moved key" noise.

Without sorting, a 200-line JSON comparison produces hundreds of position-change lines that hide the two or three real differences. With sorting, the diff is readable in under a minute.

This is the single most useful application of JSON sorting for API debugging work.

When NOT to Sort for Git

Sorting is almost always good, but there are real exceptions:

package.json top-level keys. Convention puts name and version first, not alphabetized. Use sort-package-json npm tool to preserve this convention while sorting inner dependency objects.

OpenAPI/Swagger specs. The openapi version field is expected at the top. Paths are typically grouped by resource, not alphabetized. Sorting may hurt readability here.

Ansible playbooks and Kubernetes manifests. These have conventional top-level ordering (apiVersion, kind, metadata, spec). Sorting breaks the reading flow.

JSON fixtures for tests. If the test depends on a specific key order (rare but real), sorting breaks the test.

For these cases, sort only the inner arrays or dicts where order is truly arbitrary, and preserve the conventional top-level structure. Manual sorting in the browser lets you sort selectively; full tooling like Prettier plugin sorts everything.

Frequently Asked Questions

Will sorting JSON break git history or blame?

Yes — the one-time sort commit will show "all lines changed" on that commit. Future blames on that file will point to the sort commit for each line. Either accept this (most teams do), or use git blame with the -w flag to ignore whitespace-only changes (helps in some but not all cases).

Does sort-package-json preserve conventional ordering?

Yes. sort-package-json is specifically designed to keep name, version, description, main, scripts at the top in conventional order while alphabetizing dependencies, devDependencies, and other inner objects. It is the right tool for package.json specifically.

Can I sort and commit JSON in one command?

Yes with Husky + lint-staged: commits automatically sort any JSON you touched. Alternative: a manual npm script "sort-config": "prettier --write .", then "git add" after.

What about JSON Lines (.jsonl) files?

Each line is an independent JSON object. Sort the keys within each line individually if you want deterministic byte output per record. Our browser tool does not process JSONL as a unit; you would sort line-by-line or write a small script.