Handling Package Lock File Conflicts

Lock File Conflicts

Lock file conflicts (in package-lock.json, yarn.lock, or pnpm-lock.yaml) are unique because you should almost never try to manually resolve them. These files are auto-generated, contain thousands of lines, and have a precise internal structure that is nearly impossible to merge by hand correctly.

Why Lock Files Conflict

When two branches install or update different packages, each branch generates its own lock file that pins exact dependency versions and integrity hashes. Git sees these as conflicting changes to the same lines.

The Correct Resolution Strategy

Unlike most conflicts where you choose between ours and theirs, lock file conflicts should be resolved by regeneration:

1. Accept either side (usually Accept Theirs or Accept Ours — it does not matter which).
2. Ensure package.json is correct: Make sure the actual dependency list in package.json reflects what you want (merge both branches' additions).
3. Delete the lock file and regenerate it by running:
   • npm install (for package-lock.json)
   • yarn install (for yarn.lock)
   • pnpm install (for pnpm-lock.yaml)
4. Commit the regenerated lock file.

Why Manual Merge Fails

Lock files contain integrity checksums (SHA-512 hashes) that must exactly match the downloaded package contents. Manually combining two lock files almost always produces mismatched checksums, leading to installation failures.

Special Tooling

Yarn provides yarn install which automatically resolves lock file conflicts during installation. npm 7+ also handles lock file conflicts gracefully when you run npm install after accepting either side.