{"id":31262759,"url":"https://github.com/boneskull/package-lock-merge-driver","last_synced_at":"2025-09-23T11:55:03.753Z","repository":{"id":312342493,"uuid":"1045766271","full_name":"boneskull/package-lock-merge-driver","owner":"boneskull","description":"Git merge driver for resolving lockfile conflicts in npm v7.0.0+","archived":false,"fork":false,"pushed_at":"2025-09-21T05:37:25.000Z","size":925,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-21T07:21:48.476Z","etag":null,"topics":["conflict","git","lockfile","merge","merge-driver","nodejs","npm"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"npm/npm-merge-driver","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boneskull.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"boneskull"}},"created_at":"2025-08-27T17:22:15.000Z","updated_at":"2025-09-21T05:37:13.000Z","dependencies_parsed_at":"2025-09-14T01:13:45.574Z","dependency_job_id":null,"html_url":"https://github.com/boneskull/package-lock-merge-driver","commit_stats":null,"previous_names":["boneskull/package-lock-merge-driver"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/boneskull/package-lock-merge-driver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fpackage-lock-merge-driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fpackage-lock-merge-driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fpackage-lock-merge-driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fpackage-lock-merge-driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boneskull","download_url":"https://codeload.github.com/boneskull/package-lock-merge-driver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fpackage-lock-merge-driver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276570909,"owners_count":25665904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-23T02:00:09.130Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["conflict","git","lockfile","merge","merge-driver","nodejs","npm"],"created_at":"2025-09-23T11:54:58.524Z","updated_at":"2025-09-23T11:55:03.741Z","avatar_url":"https://github.com/boneskull.png","language":"TypeScript","funding_links":["https://github.com/sponsors/boneskull"],"categories":[],"sub_categories":[],"readme":"# 🔐 package-lock-merge-driver\n\n\u003e Git merge driver for `package-lock.json` v2+\n\nThis is a fork of the original (unmaintained) [`npm-merge-driver`](https://github.com/npm/npm-merge-driver) project.\n\n## What is this?\n\nThis package provides a CLI to install (and uninstall) a [merge driver](https://git-scm.com/docs/gitattributes#_defining_a_custom_merge_driver) which attempts to automatically resolve merge conflicts in `package-lock.json` files.\n\n## Do I need it?\n\nDo you get merge conflicts in your `package-lock.json` files? Like _all the damn time?_ Then yeah.\n\n## Differences from `npm-merge-driver`\n\n\u003e TL;DR: _This is a whole-ass package_.\n\n- Supports for npm workspaces (monorepos)\n- Sacrifices speed for reliability\n- Validates the result via `npm ls` to check for broken dependencies (if this fails, automatic resolution fails)\n- Default behavior is to **install merge drivers globally** (you can still install locally if you want)\n- Requires Node.js v20.0.0+\n- Requires `npm` v7.0.0+\n- Removed `--no-legacy` flag because what is even that\n- Supports Git [includes](https://git-scm.com/docs/git-config#_includes) when discovering and writing to Git configuration files\n- Will cleanup empty `gitattributes` files it created\n- Tested against an _actual Git repository_\n- Unrecognizable compared to original; don't bother\n\nIn addition, the following items are _current_ differences, but they _might_ instead become _non-differences_ in a hypothetical future:\n\n- **Use with Yarn or pnpm lockfiles is unsupported**\n- No support for `npm-shrinkwrap.json`, but you probably don't care about that\n\n\u003e I suppose if (big _if_) I do end up supporting Yarn or pnpm then I might need to rename the package. I'll think of a better name.\n\n### Motivation\n\nI needed [npm-merge-driver](https://github.com/npm/npm-merge-driver) to work. But it doesn't, and there's no way forward to fix it. So against my better judgement, here we are.\n\n## Requirements\n\n- Node.js v20.11.0+\n- npm v7.0.0+\n\n## Automatic Setup (Recommended)\n\nTo start using it right away:\n\n```sh\nnpx package-lock-merge-driver install\n```\n\nThe next time _any_ `package-lock.json` has a conflict, a merge driver will attempt to automatically fix it. Unless it fails, you don't need to do anything else. You _will_ still need to resolve conflicts in `package.json` files yourself, though!\n\n\u003e [!TIP]\n\u003e\n\u003e Once you've tried it a couple times and felt its powerful magic, it's recommended to install `package-lock-merge-driver` globally to avoid some `npx`-related overhead:\n\u003e\n\u003e ```sh\n\u003e npm install -g package-lock-merge-driver\n\u003e ```\n\u003e\n\u003e BONUS! If you install globally and are on a POSIX OS, you _should_ be able to run `man package-lock-merge-driver` to see the _man page_! Which is just this `README.md`; sorry.\n\n### Example Scenario\n\nAfter installation, you create a feature branch and make some dependency changes. Now you want to rebase onto `main`:\n\n```sh\ngit rebase main\n```\n\nEek, there's a conflict! But don't panic! You should see something like thiss:\n\n```plain\n🔐 package-lock-merge-driver v2.3.6\n\nMoved to trash: /my-repo/node_modules\npackage-lock-merge-driver: Successfully resolved conflicts in package-lock.json\nAuto-merging package-lock.json\n```\n\nDid conflicts in `package-lock.json` remain?\n\n```sh\ngit status\n```\n\n```plain\nM   package-lock.json\n```\n\nNo. No conflicts in `package-lock.json` remain.\n\n## Uninstallation\n\nThis only applies if you used the method detailed in [Automatic Setup](#automatic-setup-recommended). If you didn't, then figure it out yourself.\n\nTo remove an installed merge driver, use `package-lock-merge-driver uninstall`:\n\n```sh\nnpx package-lock-merge-driver uninstall [--global] [--name=package-lock-merge-driver]\n```\n\nThis will remove the driver from whatever Git configuration it put it in originally, and then remove it from the `gitattributes` file it used. If it created the `gitattributes` file and it is empty after removing the entry, `package-lock-merge-driver` will delete the file because it's a sweetheart.\n\n## Advanced Automated Setup\n\nThe `install` command does the actual configuration (\"installation\") of the merge driver. It supports a couple of config options:\n\n- `--command` - This is the command used for the actual merge operation. You probably don't want to fiddle with this.\n\n- `--name` - String to use as the internal driver name in your configuration. I don't know why this option is even here, but it is.\n\n- `--local` - Install the driver in the local repository only. By default, the driver is installed globally.\n\nFor example, to install the driver locally in the current working directory using a custom name:\n\n```sh\nnpx package-lock-merge-driver install --local --name=butts\n```\n\n### Verbose Logging\n\nRun any command with `--verbose` to get more output. For example:\n\n```sh\nnpx package-lock-merge-driver install --verbose\n```\n\n## Manual Setup\n\nThis is tedious.\n\n### Installation\n\n`package-lock-merge-driver` is _explicitly designed to be installed globally_. It bundles its own dependencies. You _can_ install this into a local project, but I wouldn't recommend doing so.\n\n```sh\nnpm install -g package-lock-merge-driver\n```\n\n### Configuration Details\n\n`package-lock-merge-driver`'s automated installation uses the following config:\n\n1. A merge driver in the main Git configuration, including\n   - `name` (description [really]),\n   - `driver` (the actual command)\n   - `gitAttributesPath` (path to the `gitattributes` file we will write to; this is only necessary for clean uninstallation and you can ignore it if installing manually)\n2. A `gitattributes(5)` configuration referencing `package-lock.json` and the merge driver configured in 1.\n\nIf you **do not** want `package-lock-merge-driver` to install itself for you (I guess I wouldn't blame you), here's an example of a manual global installation:\n\nAdd the driver to `~/.gitconfig`:\n\n```sh\ngit config --global merge.package-lock-merge-driver.name \\\n    \"Automatically merge npm lockfiles\"\n# this is the most important part!\ngit config --global merge.package-lock-merge-driver.driver \\\n    \"npx package-lock-merge-driver merge %A %O %B %P\"\n```\n\nAdd the relevant attributes to `~/.gitattributes` (creating if necessary):\n\n```gitattributes\npackage-lock.json merge=package-lock-merge-driver\n```\n\nThe RHS of the `merge` attribute above _must_ match `\u003cname\u003e` in `merge.\u003cname\u003e.driver`.\n\n## How it Works\n\n1. Barely.\n2. _Trash_ (read: _move to the OS' trash/recycle bin/shitcan_) `node_modules` and _any other_ `node_modules` folders found in workspaces, then re-run `npm install`.\n3. Validate result by running `npm ls`.\n\n\u003e [!NOTE]\n\u003e\n\u003e Workspaces (monorepo) support is best-effort, since `package.json` may be in conflict when we try to parse it. This will typically only affect the resulting lockfile if the actual [`workspaces` field](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#workspaces) is in conflict.\n\n### And Why It Works That Way\n\n- `npm install --package-lock-only` will not avail you as of npm v7.0.0. So that's out.\n- Running a full `npm install` every time is slow enough without a `rm -rf node_modules packages/*/node_modules` first (though I could make this configurable, I suppose), we just move them away. Your OS will take care of it. Trust me.\n  This has the advantage of mitigating churn in `package-lock.json` due to how `npm` modifies `package-lock.json` when a `node_modules` is present. If you ever see random extra fields being added and removed to `package-lock.json`, you know what I mean. I'm pretty sure this is just a bug in `npm`.\n- `npm ci` is not possible, of course, because it only works if the lockfile is valid _and_ synced with all `package.json` manifests.\n- Just accepting \"their\" `package-lock.json` doesn't help, as it will _always_ require a manual `npm install` thereafter.\n\n## A Final Plea\n\nIf you know of some way to sort out the conflicts _without_ a full `npm install`, [please file an issue](https://github.com/boneskull/package-lock-merge-driver/issues/new). Please. 🥹\n\n## Authors\n\n- Current maintainer: [Christopher Hiller](https://github.com/boneskull)\n- Original author: Kat Marchán\n\n## License\n\n- Copyright © 2025 Christopher Hiller\n- Copyright © 2017 Microsoft Corporation (a.k.a. npm, Inc. a.k.a. GitHub)\n\nThis work is released under the terms of the ISC license. See `LICENSE.md` for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboneskull%2Fpackage-lock-merge-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboneskull%2Fpackage-lock-merge-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboneskull%2Fpackage-lock-merge-driver/lists"}