{"id":28511301,"url":"https://github.com/tx3stn/vrsn","last_synced_at":"2026-06-05T08:31:15.639Z","repository":{"id":177572359,"uuid":"547763247","full_name":"tx3stn/vrsn","owner":"tx3stn","description":"A single tool for all of your semantic versioning needs.","archived":false,"fork":false,"pushed_at":"2025-06-02T09:39:06.000Z","size":88,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-08T23:42:24.668Z","etag":null,"topics":["automation","build-tools","check","ci","circleci","cli","go","golang","semantic-versioning","semver","version","version-check","version-checker","version-manager","versioning"],"latest_commit_sha":null,"homepage":"","language":"Go","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/tx3stn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","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,"zenodo":null}},"created_at":"2022-10-08T08:41:04.000Z","updated_at":"2025-06-02T09:38:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"a652e50a-15ac-4de7-9c50-534185650b6e","html_url":"https://github.com/tx3stn/vrsn","commit_stats":null,"previous_names":["thaffenden/vrsn","tx3stn/vrsn"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/tx3stn/vrsn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tx3stn%2Fvrsn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tx3stn%2Fvrsn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tx3stn%2Fvrsn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tx3stn%2Fvrsn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tx3stn","download_url":"https://codeload.github.com/tx3stn/vrsn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tx3stn%2Fvrsn/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263315872,"owners_count":23447579,"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":["automation","build-tools","check","ci","circleci","cli","go","golang","semantic-versioning","semver","version","version-check","version-checker","version-manager","versioning"],"created_at":"2025-06-08T23:40:36.974Z","updated_at":"2025-12-24T17:37:23.385Z","avatar_url":"https://github.com/tx3stn.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable MD033 --\u003e\n\u003ch1 align=\"center\"\u003evrsn\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eA single tool for \u003cstrong\u003eall\u003c/strong\u003e of your semantic versioning needs.\u003c/em\u003e\n\u003c/p\u003e\n\n![vrsn-demo](https://github.com/user-attachments/assets/9e7d5ac2-bde2-40b6-9825-27dc25647370)\n\n## Contents\n\n- [Why](#why)\n- [Install](#install)\n  - [Download from GitHub](#download-from-github)\n  - [Build it locally](#build-it-locally)\n  - [Run the Docker container](#run-the-docker-container)\n  - [Use the CircleCI orb](#use-the-circleci-orb)\n- [Commands](#commands)\n- [Setting defaults in a config file](#setting-defaults-in-a-config-file)\n- [Running in Docker](#running-in-docker)\n- [CI usage examples](#ci-usage-examples)\n\n## Why?\n\n### Language agnostic\n\nYou can run `vrsn` in a project in any (supported) language and it will work.\n\nCurrently supported version files:\n\n| File | Languages |\n| --- | --- |\n| `build.gradle`, `build.gradle.kts` | ![Java](https://img.shields.io/badge/java-%23ED8B00.svg?style=for-the-badge\u0026logo=java\u0026logoColor=white) ![Kotlin](https://img.shields.io/badge/kotlin-%237F52FF.svg?style=for-the-badge\u0026logo=kotlin\u0026logoColor=white) |\n| `Cargo.toml` | ![Rust](https://img.shields.io/badge/rust-%23000000.svg?style=for-the-badge\u0026logo=rust\u0026logoColor=white) |\n| `CMakeLists.txt` | ![C++](https://img.shields.io/badge/c++-%2300599C.svg?style=for-the-badge\u0026logo=c%2B%2B\u0026logoColor=white) |\n| `package.json` | ![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge\u0026logo=typescript\u0026logoColor=white) ![JavaScript](https://img.shields.io/badge/javascript-%23323330.svg?style=for-the-badge\u0026logo=javascript\u0026logoColor=%23F7DF1E) |\n| `pyproject.toml` | ![Python](https://img.shields.io/badge/python-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54) |\n| `setup.py` | ![Python](https://img.shields.io/badge/python-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54) |\n| `VERSION` | ![Go](https://img.shields.io/badge/go-%2300ADD8.svg?style=for-the-badge\u0026logo=go\u0026logoColor=white) + more |\n| `git tags` | ![Git](https://img.shields.io/badge/Git-F05032?style=for-the-badge\u0026logo=git\u0026logoColor=fff) |\n\nDon't see your favourite version file type in that list?\nSee the [CONTRIBUTING guide](./.github/CONTRIBUTING.md) for how to (easily) add\nsupport!\n\nIf you're the type of person that jumps between projects in different languages\nyou don't need to remember the `yarn` or `poetry` commands for each different\nproject, just use `vrsn` and get on with the important stuff.\n\n### Simple CI checks\n\nEnsuring you properly version releases is important.\n\nI've had to write semantic version checks in CI pipelines in different ways for\ndifferent languages in different jobs. Now I can just use `vrsn` and not have\nto worry about solving the same problems again.\n\n## Install\n\n### Download from GitHub\n\nFind the latest version for your system on the\n[GitHub releases page](https://github.com/tx3stn/vrsn/releases).\n\n### Build it locally\n\nIf you have go installed, you can clone this repo and run:\n\n```bash\nmake install\n```\n\nThis will build the binary and then copy it to `/usr/local/bin/vrsn` so it will be\navailable on your path. Nothing more to it.\n\n### Run the Docker container\n\nGet the Docker container from the\n[GitHub container registry](https://github.com/tx3stn/vrsn/pkgs/container/vrsn).\n\n```bash\ndocker pull ghcr.io/tx3stn/vrsn:latest\n```\n\nSee [Running in Docker](#running-in-docker) for more details.\n\n### Use the CircleCI Orb\n\nFor ease of running checks in your CI this repo includes a CircleCI orb.\nJust import the orb:\n\n```yaml\norbs:\n  vrsn: tx3stn/vrsn@volatile\n```\n\nThen use the `check-version` job in your workflow like:\n\n```yaml\nworkflows:\n  build:\n    jobs:\n      - vrsn/check-version:\n            filters:\n              branches:\n                ignore:\n                  - main\n```\n\nFor an example you can look at this repo's [CircleCI config](./.circleci/config.yml)\nwhich uses the orb.\n\nSee the [CircleCI orb docs](https://circleci.com/developer/orbs/orb/tx3stn/vrsn)\nfor more specifics on how to customise the orb jobs to best suite your needs.\n\nThe orb is semantically versioned using the same number as the `vrsn` binary\nand Docker container, so you can pin a specific version in your CI config or\nuse the `volatile` tag to always get the latest version of `vrsn`.\n\n## Commands\n\n### `--help`\n\nRun `vrsn --help` for a full up to date usage guide to get started or\n`vrsn [command] --help` if you want help with a specific command.\n\n### `check`\n\nRun `vrsn check` to automatically check versions on an existing git branch.\n\nBy default the `check` command can tell if you are on a branch that is not\nthe base branch (i.e. `main`) and will compare the version file on your current\nbranch with the version file on the base branch.\n\nThis command is super useful for running in CI, just run `vrsn check`, in your\npull request CI and `vrsn` will tell you if the version has been properly\nbumped or not.\n\nName your base branch something other than `main`?\nYou can use the `--base-branch` flag to specify the name you use.\n\nWant to run it from somewhere other than the root of your git repo? You can\nuse the `--was` and `--now` flags to pass in values from wherever you need to\ngrab them:\n\n```bash\nvrsn check --was $(\u003cfunction to get previous value\u003e) --now $(\u003cfunction to get current value\u003e)\n```\n\nYou can use the `--file` flag to point at a file that is not in the root of the\ngit repo (like in a monorepo with independantly versioned services), e.g.:\n\n```bash\nvrsn check --file './services/service-name/VERSION'\n```\n\n### `bump`\n\nRun `vrsn bump` to increment the current version file.\nIt will prompt you to select the bump type and then write the new valid semver\nversion in your version file.\n\nIf you want to avoid the interactive picker you can pass the increment level as\nan argument to the `bump` command, e.g.:\n\n```bash\nvrsn bump patch\n```\n\nWant to automatically commit the version bump? Just use the `--commit` flag. 🙌\n\nDon't like the default commit message? Provide your own custom one with\n`--commit-msg`.\n\n```bash\nversion bump minor --commit --commit-msg 'custom bump version commit message'\n```\n\nYou can use the `--file` flag to point at a file that is not in the root of the\ngit repo (like in a monorepo with independantly versioned services), e.g.:\n\n```bash\nvrsn bump --file './services/service-name/VERSION'\n```\n\nThis approach allows you to easily increment multiple versions in bulk, just\nwrite a script to iterate over each service that needs bumping and use the\n`vrsn bump` command. e.g.:\n\n```bash\nfind ./services -type f -name 'VERSION' -exec vrsn bump patch --file {} \\\n```\n\nUse git tags rather than a version file? Pass the `--git-tag` flag to read from\nthe existing tags and write a new tag. e.g.:\n\n```bash\nvrsn bump --git-tag --tag-msg 'custom tag message'\n```\n\n### Accessible mode\n\nThe `vrsn bump` command with no arguments will spawn an interactive picker.\nYou can set an `ACCESSIBLE` environment variable which will drop the TUI interactive \nselection in favour of a standard prompt that should work better with screen reader\ntools, e.g.:\n\n```bash\nACCESSIBLE='true' vrsn bump\n```\n\n![accessible mode](https://github.com/user-attachments/assets/e5238f2f-6561-470f-8f4e-ef020ca30ecc)\n\n## Setting defaults in a config file\n\nIf you always want `vrsn` to use specific flags, you can set default values for\nthem in a config file at `$XDG_CONFIG_DIR/vrsn.toml` or `$HOME/.config/vrsn.toml`.\n\nAn example config file can be found at [./.schema/vrsn.toml](./.schema/vrsn.toml).\n\nUse this file to always `--commit` by default or to always use your own custom\n`--commit-msg`.\n\n## Running in Docker\n\nTo run `vrsn` in a docker container you just need to mount the repo as a\nvolume, and `vrsn` can do it's thing, **however** git's\n[safe.directory](https://git-scm.com/docs/git-config/2.35.2#Documentation/git-config.txt-safedirectory)\nsettings would prevent `vrsn` from being able to use it's git based smarts 🧠.\n\nTo deal with this a directory called `/repo` is set as a safe directory as part\nof the Docker build process, and is configured as the container's working\ndirectory so it's recommended you use that as the destination of the volume\nmount. e.g.:\n\n```bash\ndocker run --rm -it -v $PWD:/repo vrsn:latest check\n```\n\n## CI usage examples\n\nTo auto increment a version in a dependabot pull request so you don't need to\nmanually do it:\n\n1. Configure a [write access deploy key](https://circleci.com/docs/github-integration/#deploy-keys-and-user-keys)\nin CircleCI, as the bump version command will commit the version bump to the branch.\nYou will need to pass the key fingerprint as a paramter to the `bump-version` job.\n1. Add a workflow job, filtered on branches that begin with `dependabot`, e.g.:\n\n```yaml\nworkflows:\n  pull-request-build:\n   jobs:\n    - vrsn/bump-version:\n       bump-type: patch\n       ssh-key-fingerprint: fingerprint-of-your-key\n       filters:\n         branches:\n           only:\n             - /^dependabot\\/.*/\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftx3stn%2Fvrsn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftx3stn%2Fvrsn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftx3stn%2Fvrsn/lists"}