{"id":15288025,"url":"https://github.com/arjan/vsntool","last_synced_at":"2025-04-13T06:34:56.298Z","repository":{"id":138558032,"uuid":"148327457","full_name":"arjan/vsntool","owner":"arjan","description":"Lightweight version number utility ","archived":false,"fork":false,"pushed_at":"2025-01-27T17:59:26.000Z","size":25391,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T23:04:57.879Z","etag":null,"topics":["elixir","versioning"],"latest_commit_sha":null,"homepage":"","language":"Elixir","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/arjan.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}},"created_at":"2018-09-11T14:07:55.000Z","updated_at":"2025-01-27T17:59:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"2252c7c6-a97b-4775-b81b-7bdc8ff8567a","html_url":"https://github.com/arjan/vsntool","commit_stats":null,"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arjan%2Fvsntool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arjan%2Fvsntool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arjan%2Fvsntool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arjan%2Fvsntool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arjan","download_url":"https://codeload.github.com/arjan/vsntool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248674897,"owners_count":21143761,"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":["elixir","versioning"],"created_at":"2024-09-30T15:43:51.630Z","updated_at":"2025-04-13T06:34:56.249Z","avatar_url":"https://github.com/arjan.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `vsntool` - Lean-and-mean version bumping tool\n\n[![Build Status](https://travis-ci.org/arjan/vsntool.svg?branch=master)](https://travis-ci.org/arjan/vsntool)\n\nThe `vsntool` maintains git tags and a text file, VERSION, which\ntracks the current software's version number. It provides an easy\nmethod of bumping the major, mnior and patch versions of the software.\n\nThe authoritative version of a project is in the VERSION file. `vsntool` also\nautomagically synchronizes this version number in several other auto-detected\nfiles in the repository for various frameworks and languages:\n\n- NPM packages — `package.json`\n- Expo (React Native) — `app.json` version and versionCode attributes\n- Cordova — `config.xml`; both `version=` and `android:versionCode` attributes; `plugin.xml` version\n- Erlang / OTP libraries — `src/*.app.src`\n- Android — `build.gradle` version and versionCode\n\nBy using the `vsntool` commands, the version numbers are automatically patched in these files.\n\n## Installation\n\nInstall [Elixir](https://elixir-lang.org/install.html), then execute the following in a terminal:\n\n```bash\nmix escript.install hex vsntool\n```\n\n## Usage\n\n```\n▶ vsntool\n0.1.2-1-g88547df\n```\n\nRunning `vsntool` without arguments runs `git describe --tags`, which\nretrieves the last version number, but appended with a unique\nidentifier which describes the current commit. This is handy in CI\nsystems and development setups where you often want to build or\nrelease snapshots which contain no official version.\n\nTo retrieve the last released version, run:\n\n```\n▶ vsntool last\n0.1.2\n```\n\n(which is equivalent to `cat VERSION`).\n\nThe default branch on which the releases are being tagged is\n`master` or `main`. To change this, change the environment variable\n`VSN_BRANCH`.\n\nWhen vsntool is run on a non-release branch, the branch name is added\nto the version:\n\n```\n▶ git checkout develop\n▶ vsntool\n0.1.2-1-develop.1-g88547df\n```\n\n### Initialization\n\n`vsntool init` initializes a VERSION file in a directory and ensures\nit has a git repository:\n\n```\n▶ mkdir ~/new-project; cd ~/new-project\n▶ vsntool init\nInitialized git repository\nVersion bump to 0.0.1 OK.\n```\n\n### Version bumping\n\nOnce a repo has been initialized, you can use the `bump_major`,\n`bump_minor` and `bump_patch` commands to increase the version number:\n\n```\n▶ vsntool bump_patch\nVersion bump to 0.1.2 OK.\n```\n\nNote that vsntool will refuse to tag a commit twice:\n\n```\n▶ vsntool bump_patch\nCurrent commit is already tagged (0.1.2)\n```\n\nTo release a new version, do another commit before doing another version bump,\nor use the `FORCE=true` environment variable to force the version.\n\n### Development versions / Release candidates workflow\n\nUsually after a release you want to set the current project version to a `dev`\nprefix to indicate that this is the current working version. You do this by\nspecifying `--dev` as a flag:\n\n```\n▶ vsntool bump_minor --dev\nVersion bump to 0.1.0-dev OK.\n```\n\n\u003e A `--dev` bump will **not** create a git tag.\n\nOnce you are happy with your project, bump it to a release candidate:\n\n```\n▶ vsntool bump_rc\nVersion bump to 0.1.0-rc.0 OK.\n```\n\nAnd create as many release candidates after that as you want:\n\n```\n▶ vsntool bump_rc\nVersion bump to 0.1.0-rc.1 OK.\n```\n\nTo promote an `dev` or `rc` version to a release, call `vsntool release`:\n\n```\n▶ vsntool release\nVersion bump to 0.1.0 OK.\n```\n\n### Usage in Elixir projects\n\nTracking your Elixir project's version number is easy; in your\n`mix.exs` file, you don't hardcode the version number but instead read\nit from the VERSION file:\n\n```elixir\n  def project do\n    [\n      app: :myproject,\n      version: File.read!(\"VERSION\")\n      ...\n```\n\nThis file is evaluated at compile time, so there is no runtime dependency on the existence of the VERSION file.\n\nWhen releasing your library as dependency, do not forget to add the VERSION file to the list of to-be-packaged files:\n\n```elixir\n  defp package do\n    %{\n      files: [\"lib\", \"mix.exs\", \"*.md\", \"LICENSE\", \"VERSION\"],\n      ...\n```\n\n### Usage with docker\n\nBuild the current project and tag it with the correct version:\n\n```\n▶ docker build . -t organisation/projectname:$(vsntool)\n```\n\n## Plugins\n\nvsntool \"knows\" about a few common places where version numbers are stored, and\nwill detect these automatically, using a plugin system. The currently supported\nand shipped plugins are:\n\n- Support for npm `package.json` files\n- Expo (React Native)'s `app.json`, both version and versionCode\n- Android apps, `build.gradle`, both versionName and versionCode\n- Cordova apps, `config.xml`, both version and versionCode\n- Cordova apps, `plugin.xml`\n\n## Hooks\n\nTo execute code just before a version bump, you can create a file called\n`.vsntool/hooks/pre_persist`, which gets called with a single argument, the\nversion that is going to be bumped.\n\n## Bash / zsh completion\n\nTo enable command completion, add the following to your `~/.zshrc` or `~/.bashrc`:\n\n```\ncomplete -W \"init bump_major bump_minor bump_patch last\" vsntool\n```\n\n## Building\n\nvsntool is an Elixir project, but builds as an _escript_, a self-contained binary. To build it, you need to have Elixir installed, then run:\n\n```\n▶ make\n```\n\nThis produces a fresh version of the `vsntool` binary in the root of the repository. Happy versioning!\n\n## Features / todo list\n\n- [x] Plugin system for updating version in framework-specific files\n- [x] Add support for dev versions (1.0.0-dev)\n- [x] Add support for release-candidate-like versions (1.0.0-rc1)\n- [ ] Improve error reporting, error messages (stop using `:os.cmd`)\n- [ ] Use [artificery](https://github.com/bitwalker/artificery) for command parsing\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farjan%2Fvsntool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farjan%2Fvsntool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farjan%2Fvsntool/lists"}