{"id":13817179,"url":"https://github.com/FormidableLabs/publish-diff","last_synced_at":"2025-05-15T19:31:04.038Z","repository":{"id":66030473,"uuid":"70753000","full_name":"FormidableLabs/publish-diff","owner":"FormidableLabs","description":"Preview npm publish changes.","archived":false,"fork":false,"pushed_at":"2019-12-30T21:00:59.000Z","size":58,"stargazers_count":91,"open_issues_count":5,"forks_count":3,"subscribers_count":50,"default_branch":"master","last_synced_at":"2025-04-06T07:37:57.661Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FormidableLabs.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-10-13T00:21:55.000Z","updated_at":"2025-03-20T12:51:16.000Z","dependencies_parsed_at":"2023-03-10T23:32:16.856Z","dependency_job_id":null,"html_url":"https://github.com/FormidableLabs/publish-diff","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FormidableLabs%2Fpublish-diff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FormidableLabs%2Fpublish-diff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FormidableLabs%2Fpublish-diff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FormidableLabs%2Fpublish-diff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FormidableLabs","download_url":"https://codeload.github.com/FormidableLabs/publish-diff/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254407270,"owners_count":22066204,"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","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":[],"created_at":"2024-08-04T06:00:36.240Z","updated_at":"2025-05-15T19:31:03.707Z","avatar_url":"https://github.com/FormidableLabs.png","language":"JavaScript","readme":"[![Travis Status][trav_img]][trav_site]\n[![Maintenance Status][maintenance-image]](#maintenance-status)\n\u003c!--[![Coverage Status][cov_img]][cov_site]--\u003e\n\n\n\nPublish Diff\n============\n\nView diffs of what you _will_ publish to `npm` **before** you really do!\n\nPublishing a package from a local repository runs the risk of last minute\nhuman mistakes like:\n\n- deletions\n- mutations\n- additions\n\nto the files sent to the `npm` registry.\n\n`publish-diff` offers the piece of mind that you will publish exactly what you\nintend to publish with convenient, **git-style diffs** against the `npm`\nregistry from your local project.\n\n\n## Installation\n\nInstall this package as a global dependency.\n\n```sh\n$ npm install -g publish-diff\n```\n\n## Usage\n\nThe basics:\n\n\n```\n  Usage: publish-diff [options]\n\n  Preview npm publish changes.\n\n\n  Options:\n\n    -V, --version              output the version number\n    -o, --old \u003cpackage\u003e        Old package to diff (default `\u003cpackage\u003e@latest`)\n    -n, --new \u003cpackage\u003e        New package to diff (default `process.cwd()`)\n    -r, --registry \u003cregistry\u003e  The npm registry to diff the package against\n    -f, --filter \u003cpattern\u003e     File glob patterns to filter to\n    --no-colors                Disable colors in the outputted diff\n    -h, --help                 output usage information\n\n  Examples:\n\n    # Compare (old) npm registry `latest` version vs. (new) local `process.cwd()`\n    $ publish-diff\n\n    # Compare (old) npm version vs. (new) latest npm version\n    $ publish-diff -o rowdy@0.4.0 -n rowdy@latest\n\n    # Compare (old) git tag/hash vs. (new) git tag/hash\n    $ publish-diff -o FormidableLabs/rowdy#v0.4.0 -n FormidableLabs/rowdy#v0.5.0\n\n    # Filter differences to only lib and src directories\n    $ publish-diff -o radium@0.21.1 -n radium@0.21.2 --filter='{lib,src}/**'\n\n    # Filter differences to ignore dist directory\n    $ publish-diff -o radium@0.21.1 -n radium@0.21.2 --filter='!dist/**'\n```\n\n### Local Diffs\n\nThe most common case is to compare the `latest` published version of a\npackage (old) against the current working directory (new). In this case,\n`publish-diff` will infer the package's `name` from the `package.json` file.\n\n```sh\n$ publish-diff\n```\n\nThe script takes `-o|--old` and `-n|--new` values to determine what to diff.\n\n* `-n|--new`: Defaults to current working directory (`process.cwd()`) in the\n  local filesystem. This assumes the common case of publishing a new version\n  from your machine.\n* `-o|--old`: Defaults to the `package.json:name` of the package extracted from\n  the `--new` argument at its latest version in the `npm` registry.\n\nFor a package `\u003cpkg\u003e` already published to the `npm` registry the default case\nexpands to:\n\n```sh\n$ publish-diff -o \u003clocal cwd\u003e -n \u003clatest npm version\u003e\n\n# Diff local version vs latest on npm registry\n$ publish-diff\n$ publish-diff -n .\n$ publish-diff -o \u003cpkg\u003e@latest -n .\n$ publish-diff -o \u003cpkg\u003e@latest\n\n# Diff local version vs tag or old version\n$ publish-diff -o \u003cpkg\u003e@beta\n$ publish-diff -o \u003cpkg\u003e@1.2.3\n\n# Diff local version vs other local version\n$ publish-diff -o /path/to/some-version\n$ publish-diff -o /path/to/some-version -n .\n$ publish-diff -o /path/to/some-version -n /path/to/other-version\n```\n\n### Remote Diffs\n\nUnder the hood, `publish-diff` relies on the amazingly flexible\n[`npm pack`](https://docs.npmjs.com/cli/pack) to create the \"real deal\" version\nof a package that is already / will be published. This also gives us some extra\nflexibility in specifying the old and new packages to compare against as\n`publish-diff` permits passing the `-o` and `-n` arguments with any value that\nwould otherwise be permissible to `npm pack`.\n\nThis means you can view remote differences across already published versions of\npackages without needing a local checkout:\n\n```sh\n$ publish-diff -n \u003cnpm name + version\u003e\n$ publish-diff -o \u003cnpm name + version\u003e -n \u003cnpm name + version\u003e\n\n# Diff old version vs. latest on npm registry\n$ publish-diff -o rowdy@0.4.0   -n rowdy@latest\n$ publish-diff -o radium@0.17.2 -n radium\n\n# Diff two old versions on npm registry\n$ publish-diff -o rowdy@0.4.0   -n rowdy@0.5.0\n$ publish-diff -o radium@0.17.2 -n radium@0.18.0\n```\n\nAnd you can do the same with git versions:\n\n```sh\n# Diff git tag/hash vs latest on npm registry\n$ publish-diff -o FormidableLabs/rowdy#v0.4.0  -n rowdy\n$ publish-diff -o FormidableLabs/rowdy#504735c -n rowdy@latest\n$ publish-diff -o FormidableLabs/rowdy#v0.4.0  -n rowdy@latest\n\n# Diff two old versions from git tag/hash\n$ publish-diff -o FormidableLabs/rowdy#v0.4.0  -n FormidableLabs/rowdy#v0.5.0\n$ publish-diff -o FormidableLabs/rowdy#504735c -n FormidableLabs/rowdy#fe25a22\n```\n\nNote that when doing local / git-based comparisons that portions of the `npm`\npublish / version lifecycles may be missing and you may need to manually\napproximate this (discussed in detail in the next section).\n\n### npm Lifecycle Complexities\n\nOne complexity that comes up frequently is `npm` lifecycle events that occur\nin publishing that need to be simulated to accurately generate a preview diff.\nSpecifically, if the following taks is present in a `package.json` file, it\nwill occur before actual publishing:\n\n- `prepublish`\n\nAfter publishing, the following tasks run if found:\n\n- `publish`\n- `postpublish`\n\nIf a project uses an `npm version` workflow to control versioning of git source\nit will invoke the following `package.json` tasks if found:\n\n- `preversion`\n- `version`\n\nAfter versioning, the following task is run if found:\n\n- `postversion`\n\nTranslating this to `publish-diff`, if you want to simulate what will actually\nbe published, a more accurate command line sequence would be:\n\n```sh\n$ npm run prepublish \u0026\u0026 \\\n  publish-diff \u0026\u0026 \\\n  npm run postpublish\n```\n\nThe gotcha here is that if there is a `package.json:publish` script it would\nnot be run and you will need to manually approximate that because running\n`npm run publish` would **actually publish**, defeating the point of previewing\nyour diff.\n\nFor a `version` workflow, an appropriate command line sequence may look\nsomething like:\n\n```sh\n$ npm run preversion \u0026\u0026 \\\n  publish-diff \u0026\u0026 \\\n  npm run postversion\n```\n\nSimilar to `publish`, you would not want to run `npm run version` because it\nhas side effects -- in this case, mutating the git state of your project.\nProjects with an actual `package.json:version` script would need manual cleanup.\n\n## Notes\n\n### `.npmrc` Files\n\n`publish-diff` follows the `npm` rules for searching for `.npmrc` files --\nhttps://docs.npmjs.com/files/npmrc#files -- which approximates to:\n\n- `${process.cwd()}/.npmrc`\n- `~/.npmrc`\n- `$NODE_GLOBAL_PATH/etc/npmrc`\n- `$SYSTEM_PATH/npm/npmrc`\n\n`publish-diff` shells to `npm pack` which will out-of-the-box work with all but\nthe first of these rc file locations. The complexity is that for the actual\n`npm pack` command, `publish-diff` creates and switches to a temporary\ndirectory. To compensate for this behavior, if a `${process.cwd()}/.npmrc` file\nis found, that is _also_ copied to the temporary directory before initiating\nany underlying `npm` commands.\n\n### Maintenance Status\n\n**Stable:** Formidable is not planning to develop any new features for this project. We are still responding to bug reports and security concerns. We are still welcoming PRs for this project, but PRs that include new features should be small and easy to integrate and should not include breaking changes.\n\n[trav_img]: https://api.travis-ci.org/FormidableLabs/publish-diff.svg\n[trav_site]: https://travis-ci.org/FormidableLabs/publish-diff\n[cov_img]: https://img.shields.io/coveralls/FormidableLabs/publish-diff.svg\n[cov_site]: https://coveralls.io/r/FormidableLabs/publish-diff\n[maintenance-image]: https://img.shields.io/badge/maintenance-stable-blue.svg\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFormidableLabs%2Fpublish-diff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFormidableLabs%2Fpublish-diff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFormidableLabs%2Fpublish-diff/lists"}