{"id":13564341,"url":"https://github.com/mpanarin/versioce","last_synced_at":"2025-10-21T19:01:43.376Z","repository":{"id":46533506,"uuid":"296918819","full_name":"mpanarin/versioce","owner":"mpanarin","description":"Version bumping and changelog generation for your mix project","archived":false,"fork":false,"pushed_at":"2024-03-13T14:56:42.000Z","size":132,"stargazers_count":30,"open_issues_count":2,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-04T17:47:25.469Z","etag":null,"topics":["bump","bumpversion","changelog","elixir","versioning","versions"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/versioce/readme.html","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mpanarin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2020-09-19T17:29:22.000Z","updated_at":"2024-10-18T09:47:53.000Z","dependencies_parsed_at":"2024-05-01T17:21:11.183Z","dependency_job_id":"bfa1d5cf-6d50-4314-ab50-17dd5c503f39","html_url":"https://github.com/mpanarin/versioce","commit_stats":{"total_commits":76,"total_committers":3,"mean_commits":"25.333333333333332","dds":0.03947368421052633,"last_synced_commit":"406d1204aad65ea769a609bddcbb516773ad5bd2"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpanarin%2Fversioce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpanarin%2Fversioce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpanarin%2Fversioce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpanarin%2Fversioce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mpanarin","download_url":"https://codeload.github.com/mpanarin/versioce/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247082918,"owners_count":20880744,"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":["bump","bumpversion","changelog","elixir","versioning","versions"],"created_at":"2024-08-01T13:01:29.998Z","updated_at":"2025-10-21T19:01:43.369Z","avatar_url":"https://github.com/mpanarin.png","language":"Elixir","funding_links":[],"categories":["Release Management"],"sub_categories":[],"readme":"# Versioce\n[![Hex version badge](https://img.shields.io/hexpm/v/versioce.svg)](https://hex.pm/packages/versioce)\n[![Actions Status](https://github.com/mpanarin/versioce/workflows/Elixir%20CI/badge.svg)](https://github.com/mpanarin/versioce/actions)\n[![Code coverage badge](https://img.shields.io/codecov/c/github/mpanarin/versioce/master.svg)](https://codecov.io/gh/mpanarin/versioce/branch/master)\n[![License badge](https://img.shields.io/hexpm/l/versioce.svg)](https://github.com/mpanarin/versioce/blob/master/LICENSE.md)\n\nThis is a mix task to bump version of your project.\nVersioce includes batteries that are customizable for your liking.\nIt is heavily inspired by [bumpversion](https://github.com/peritus/bumpversion).\n\n## Quick links\n- [Installation](#installation)\n- [Migrating from older versions](#migrating-from-older-versions)\n- [Usage](#usage)\n  - [Configure the files](#configure-the-files)\n  - [Configure Hooks](#configure-hooks)\n    - [Pre Hooks](#pre-hooks)\n    - [Post Hooks](#post-hooks)\n  - [Bump your versions!](#bump-your-versions)\n    - [CalVer](#calver)\n  - [Changelog generation](#changelog-generation)\n- [The name](#the-name)\n- [Similar projects](#similar-projects)\n- [Some acknowledgments](#some-acknowledgments)\n\n## Installation\n\nThe [package](https://hex.pm/packages/versioce) can be installed by adding `versioce` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:versioce, \"~\u003e 2.0.0\"}\n  ]\nend\n```\n\n## Migrating from older versions\nMajor versions bring braking changes or deprecations.\nFor migration instructions see [Migrations doc](docs/migrations.md)\n\n## Usage\n\n### Configure the files\n\nYou should let `Versioce` know what files you want your version bumped in.\nBy default only the files `README.md` and `mix.exs` are used.\nYou can add additional files to this list in the config\n```elixir\nconfig :versioce,\n  files: [\n    \"README.md\",\n    \"docker/Dockerfile\"\n  ]\n```\n\u003e Note: All file paths should be relative to the `mix.exs` file. `mix.exs` will **always** be used and bumped\n\u003e as it is the **core** file, from which `versioce` will pick your current version. This was done in order\n\u003e to remove any additional config files (ex. `.bumpversion.cfg` in bumpversion).\n\n### Configure Hooks\n\n`Versioce` is agnostic of your VCS(although has hooks for git) or other things you need to do.\nSome people want to generate changelogs, some - automatically notify teammates\nat slack, publish package to hex, etc.\n\nTo make it possible - `Versioce` has Hooks. There are `pre` hooks and `post` hooks.\nHook is a list of simple elixir modules that have `run` function in them.\n\n\u003e Check other available configurations in [config docs](Versioce.Config.html)\n\n#### Pre hooks\n\nAre fired before any of the bumping is done.\\\nCheck available built-in [pre hooks](docs/available_hooks.md#pre-hooks)\\\nThey receive all the parameters for the `bump` task as a list of strings.\nWhich they can use for their side-effects. But they are **required** to return\nthis list.\\\nThe result of the first hook will be piped into the next one.\n\n```elixir\ndefmodule MyProj.Versioce.PreHook do\n  use Versioce.PreHook\n  def run(params) do\n    IO.inspect(params)\n    {:ok, params}\n  end\nend\n```\nAnd in your config:\n```elixir\nconfig :versioce,\n  pre_hooks: [MyProj.Versioce.PreHook],\n```\nAfter that:\n```\n\u003e mix bump.version\n0.1.0\n\u003e mix bump patch\nRunning pre-hooks: [MyProj.Versioce.PreHook]\n[\"patch\"]\nBumping version from 0.1.0:\n0.1.1\nRunning post-hooks: []\n```\n\n#### Post hooks\n\nWork the same as pre hooks. The only differences are:\n1. They are fired after all the version bumping\n2. Their `run` function receives a `version` which was bumped to instead of params.\\\nCheck available built-in [post hooks](docs/available_hooks.md#post-hooks)\n\n```elixir\ndefmodule MyProj.Versioce.PostHook do\n  use Versioce.PostHook\n  def run(version) do\n    IO.inspect(version)\n    {:ok, version}\n  end\nend\n```\nAnd in your config:\n```elixir\nconfig :versioce,\n  post_hooks: [MyProj.Versioce.PostHook],\n```\nAfter that:\n```\n\u003e mix bump.version\n0.1.0\n\u003e mix bump patch\nRunning pre-hooks: []\nBumping version from 0.1.0:\n0.1.1\nRunning post-hooks: [MyProj.Versioce.PostHook]\n\"0.1.1\"\n```\n\n### Bump your versions!\n\nSimply run `mix bump` with the preferred binding or a ready version.\n```\n\u003e mix bump.version\n0.1.0\n\u003e mix bump patch\nRunning pre-hooks: []\nBumping version from 0.1.0:\n0.1.1\nRunning post-hooks: []\n\u003e mix bump major\nRunning pre-hooks: []\nBumping version 0.1.1:\n1.0.0\nRunning post-hooks: []\n\u003e mix bump 2.0.2\nRunning pre-hooks: []\nBumping version from 1.1.1:\n2.0.2\nRunning post-hooks: []\n```\n\nYou can also add pre-release or build information easily with `--pre` or `--build`\n```\n\u003e mix bump.version\n0.1.0\n\u003e mix bump --pre alpha.3\nRunning pre-hooks: []\nBumping version from 0.1.0:\n0.1.0-alpha.3\nRunning post-hooks: []\n\u003e mix bump --build 20210101011700.amd64\nRunning pre-hooks: []\nBumping version from 0.1.0-alpha.3:\n0.1.0-alpha.3+20210101011700.amd64\nRunning post-hooks: []\n```\n\nAfter using `--pre` or `--build` you may want to bump to a full normal version.\nWhile Versioce does not directly support it, it has a handy task `bump.version.normal`, which will return a normal version. You can use it in `bump` task\n\n```\n\u003e mix bump.version\n0.1.0\n\u003e mix bump --pre alpha.3\nRunning pre-hooks: []\nBumping version from 0.1.0:\n0.1.0-alpha.3\nRunning post-hooks: []\n\u003e mix bump.version\n0.1.0-alpha.3\n\u003e mix bump.version.normal\n0.1.0\n\u003e mix bump \"$(mix bump.version.normal)\"\nRunning pre-hooks: []\nBumping version from 0.1.0-alpha.3:\n0.1.0\nRunning post-hooks: []\n```\n\n#### CalVer\nVersioce has a limited support for [CalVer](https://calver.org/).\n\nBe aware that it is supported lazily, ie. if you start using regular semantic versioning you will need to make a bump to a specific sematic version first,\notherwise Versioce will bump your calver version like it is a semantic one. This is probably not what you want.\n\nCalVer also currently does not support `--pre` and `--build` params, they will be ignored.\nFor the available formats of the calver consult the [config docs](Versioce.Config.html)\n\n```\n\u003e mix bump.version\n0.1.0\n\u003e mix bump calver\nRunning pre-hooks: []\nBumping version from 0.1.0:\n2022.11.28\nRunning post-hooks: []\n```\n\n### Changelog generation\n\nVersioce has the functionality to generate changelogs. By default it produces a changlog in the [Keepachangelog](https://keepachangelog.com/en/1.0.0/) format\nfrom your Git history, but both can be configured:\n``` elixir\nconfig :versioce, :changelog,\n  datagrabber: Versioce.Changelog.DataGrabber.Git,        # Or your own datagrabber module\n  formatter: Versioce.Changelog.Formatter.Keepachangelog  # Or your own formatter module\n```\nMake sure to set the proper anchors configuration according to your repository policies, so Versioce can place entries in the proper sections:\n\n``` elixir\nconfig :versioce, :changelog,\n  anchors:\n      %{\n        added: [\"[ADD]\"],\n        changed: [\"[IMP]\"],\n        deprecated: [\"[DEP]\"],\n        removed: [\"[REM]\"],\n        fixed: [\"[FIXED]\"],\n        security: [\"[SEC]\"]\n      }\n```\n\u003e Anchors definition should follow the `Versioce.Changelog.Anchors` struct format. As it will be converted to it down the line.\n\nAnd you're all set!\nNow you can either run a `mix changelog` task to generate a changelog file\nor add `Versioce.PostHooks.Changelog` post hook in your configuration:\n``` elixir\nconfig :versioce,\n  post_hooks: [Versioce.PostHooks.Changelog],\n```\n\u003e *Important*: If you want to use this hook in combination with `Versioce.PostHooks.Git.Release`, make sure that changelog is *before* the release hook, as well as either `Versioce.Config.Git.dirty_add/0` is enabled or your changelog file is added to `Versioce.Config.Git.additional_files/0`\\\n\u003e Make sure to check other configurations for the changelog generation in `Versioce.Config.Changelog`\n\n## The name\n\nThe name `Versioce` is a play on Italian brand Versace with a word version.\\\nIt obviously has no connection to it.\\\nI obviously lack any creativity or imagination.\n\n## Similar projects\n\n  * https://github.com/glasnoster/eliver\n  * https://github.com/oo6/mix-bump\n  * https://github.com/zachdaniel/git_ops\n\n## Some acknowledgments\n\nA huge inspiration for this project was Elixir conf talk by Jeremy Searls\\\nWhich I highly recommend you to [watch](https://www.youtube.com/watch?v=zTHCEZVL4Kw)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmpanarin%2Fversioce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmpanarin%2Fversioce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmpanarin%2Fversioce/lists"}