{"id":16347814,"url":"https://github.com/privatenumber/git-publish","last_synced_at":"2025-03-16T15:31:11.198Z","repository":{"id":53923985,"uuid":"521798544","full_name":"privatenumber/git-publish","owner":"privatenumber","description":"☁️ Publish your npm package to a GitHub repository branch","archived":false,"fork":false,"pushed_at":"2024-03-12T06:40:02.000Z","size":741,"stargazers_count":46,"open_issues_count":4,"forks_count":1,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2024-05-04T00:17:52.862Z","etag":null,"topics":["branch","branches","git","github","npm","publish"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/privatenumber.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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},"funding":{"github":"privatenumber"}},"created_at":"2022-08-05T23:17:53.000Z","updated_at":"2024-04-27T15:25:47.000Z","dependencies_parsed_at":"2024-03-12T06:49:48.099Z","dependency_job_id":null,"html_url":"https://github.com/privatenumber/git-publish","commit_stats":{"total_commits":27,"total_committers":2,"mean_commits":13.5,"dds":"0.37037037037037035","last_synced_commit":"1714d3eb80843e23a2c24ec759fb1b499967621e"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/privatenumber%2Fgit-publish","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/privatenumber%2Fgit-publish/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/privatenumber%2Fgit-publish/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/privatenumber%2Fgit-publish/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/privatenumber","download_url":"https://codeload.github.com/privatenumber/git-publish/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243822312,"owners_count":20353496,"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":["branch","branches","git","github","npm","publish"],"created_at":"2024-10-11T00:46:10.524Z","updated_at":"2025-03-16T15:31:11.180Z","avatar_url":"https://github.com/privatenumber.png","language":"TypeScript","funding_links":["https://github.com/sponsors/privatenumber","https://github.com/sponsors/privatenumber/sponsorships?tier_id=398771","https://github.com/sponsors/privatenumber/sponsorships?tier_id=416984"],"categories":[],"sub_categories":[],"readme":"# git-publish\n\nPublish your npm package to a Git branch. Great for pre-publishing a package for testing.\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n\t\u003ca href=\"https://github.com/sponsors/privatenumber/sponsorships?tier_id=398771\"\u003e\u003cimg width=\"412\" src=\"https://raw.githubusercontent.com/privatenumber/sponsors/master/banners/assets/donate.webp\"\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/sponsors/privatenumber/sponsorships?tier_id=416984\"\u003e\u003cimg width=\"412\" src=\"https://raw.githubusercontent.com/privatenumber/sponsors/master/banners/assets/sponsor.webp\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Why?\n\nTo test a package without publishing to npm.\n\n#### Why not use `npm publish` to make a pre-release?\n\nBecause of the following drawbacks:\n\n- **Versioning concerns:** even though you're just testing, you still need to version bump\n- **Undeleteable:** releases are hard to remove due to npm's [strict unpublish policy](https://docs.npmjs.com/policies/unpublish)\n- **Unverifyable:** npm does not offer a great way to browse the contents of a package\n- **Risky:** Publishing tests to a production environment can be dangerous (eg. accidentally publish as stable)\n\n#### What about `npm link`?\n- No [npm life cycle scripts](https://docs.npmjs.com/cli/v8/using-npm/scripts#life-cycle-scripts)\n- Includes non-publishable assets\n- Doesn't install dependencies\n\n\n#### So why `git-publish`?\n\n- **No versions:** Instead of versions, branch names are used. Branches can be updated to reflect latest change.\n\n- **Deletable:** Simply delete the branch when you're done with it.\n\n- **Browsable:** Use GitHub to easily verify the contents of the branch. You can even share a link for others to see.\n\n- **Dev environment:** Low risk of mistakes.\n\n- **Simulates `npm publish`:** Runs npm life cycle scripts and only includes publishable assets.\n\n## Usage\n\nPublish your npm package to a branch on the Git repository:\n\n```sh\nnpx git-publish\n```\n\nThis command will publish to the remote branch `npm/\u003ccurrent branch\u003e`.\n\n\n### Global install\nKeep the command handy by installing it globally:\n\n```sh\nnpm install -g git-publish\n```\n\nWhen globally installed, you can use it without `npx`:\n```sh\ngit-publish\n```\n\n### Flags\n| Flag | Description |\n| - | - |\n| `-b, --branch \u003cbranch name\u003e` | The branch to publish the package to. Defaults to prefixing \"npm/\" to the current branch or tag name. |\n| `-r, --remote \u003cremote\u003e` | The remote to push to. (default: `origin`) |\n| `-o, --fresh` | Publish without a commit history. Warning: Force-pushes to remote |\n| `-d, --dry` | Dry run mode. Will not commit or push to the remote. |\n| `-h, --help` | Show help |\n| `--version` | Show version |\n\n## FAQ\n\n### What are some use-cases where this is useful?\n- When you want to test a new package that isn't ready to be published on npm.\n\n- When you're contributing to an open source project so you don't have publish access, but want to test the changes in a production-like environment.\n\n- When you want to test in a remote environment so you can't use `npm link`.\n\n- When you want to avoid using `npm link` because of symlink complexities.\n\n\n### How can I include a build step?\n\nLike `npm publish`, you can call the build command it in the [`prepack` script](https://docs.npmjs.com/cli/v8/using-npm/scripts#:~:text=on%20npm%20publish.-,prepack,-Runs%20BEFORE%20a).\n\n### What does this script do?\n\n1. If publish branch exists on remote, check it out to apply changes on top. Otherwise, create a new branch.\n2. Run [npm  hooks](https://docs.npmjs.com/cli/v8/using-npm/scripts) `prepare` \u0026 `prepack`\n3. Detect and commit only the [npm publish files](https://github.com/npm/npm-packlist)\n4. Push the branch to remote\n6. Print the installation command for the branch\n\n### Why is the commit history preserved in the publish branch?\n\nWhen pushing an npm installable commit to Git, it's important that it's an attached commit.\n\nThis is because npm lock references the commit hash, and not the branch name. So if the commit is detached, it will be removed upon reference loss and any subsequent npm installations referencing that commit hash will fail.\n\nIf you'd like a publish branch with a clean commit history despite these drawbacks, you can use the `--fresh` flag to force-push a single-commit branch to the remote.\n\n### How is this different from simply committing the files to a branch?\n\n- There can be missing distribution files (eg. files outside of `dist`). _git-publish_ uses [npm-packlist](https://github.com/npm/npm-packlist) —the same library `npm publish` uses—to detect publish files declared via `package.json#files` and `.npmignore`.\n- Irrelevant files are committed (eg. source files). This can slow down installation or even interfere with the library behavior. For example, if your project has development configuration files, they can accidentally be read by the dependent tooling.\n\n- npm hooks are not executed. _git-publish_ simulates package packing and runs hooks `prepare` and `prepack`.\n\n### Can I publish to and install from a private repository?\n\nYes, if using a Git client authorized to access the private repository.\n\nIf it must be publicly accessible, you can set the `--remote \u003cremote\u003e` flag to push the publish assets to a public repository. It's recommended to compile and minify the code if doing this with private code.\n\n\n#### User story\nYou want to test a branch on a private repository _Repo A_, but GitHub Actions on the consuming project _Repo B_ doesn't have access to the private repository so `npm install` fails.\n\nTo work around this, you can publish the branch to _Repo B_ to install it from there:\n\n```sh\n$ npx git-publish --remote git@github.com:repo-b.git --branch test-pkg\n\n✔ Successfully published branch! Install with command:\n  → npm i 'repo-b#test-pkg'\n```\n\n## Sponsors\n\n\u003cp align=\"center\"\u003e\n\t\u003ca href=\"https://github.com/sponsors/privatenumber\"\u003e\n\t\t\u003cimg src=\"https://cdn.jsdelivr.net/gh/privatenumber/sponsors/sponsorkit/sponsors.svg\"\u003e\n\t\u003c/a\u003e\n\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprivatenumber%2Fgit-publish","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprivatenumber%2Fgit-publish","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprivatenumber%2Fgit-publish/lists"}