{"id":23331077,"url":"https://github.com/sassoftware/gotagger","last_synced_at":"2026-03-02T16:02:28.580Z","repository":{"id":37539310,"uuid":"331729077","full_name":"sassoftware/gotagger","owner":"sassoftware","description":"A CLI and library for managing versions and git tags based on conventional commit messages.","archived":false,"fork":false,"pushed_at":"2025-03-31T19:48:24.000Z","size":684,"stargazers_count":5,"open_issues_count":6,"forks_count":8,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-09T16:09:11.854Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sassoftware.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-21T19:14:40.000Z","updated_at":"2025-01-06T22:11:59.000Z","dependencies_parsed_at":"2023-02-17T05:46:07.527Z","dependency_job_id":"d1bf8099-ab30-4f49-b7ba-5259c69be53f","html_url":"https://github.com/sassoftware/gotagger","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sassoftware%2Fgotagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sassoftware%2Fgotagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sassoftware%2Fgotagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sassoftware%2Fgotagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sassoftware","download_url":"https://codeload.github.com/sassoftware/gotagger/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248065283,"owners_count":21041871,"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-12-20T22:30:44.660Z","updated_at":"2026-03-02T16:02:28.498Z","avatar_url":"https://github.com/sassoftware.png","language":"Go","funding_links":[],"categories":["others"],"sub_categories":[],"readme":"# gotagger\n\n## Overview\n\n`gotagger` is a library and CLI\nfor tagging releases in git repositories\nas part of a CI process.\n\n`gotagger` looks through the git history of the current commit\nfor the latest semantic version.\nThis becomes the \"base\" version.\nThen `gotagger` examines all of the commit messages\nbetween the current commit and the latest tag,\nto determine if the most significant change was a\nfeature,\nbug fix,\nor breaking change\nper the [Conventional Commits] format.\n`gotagger` then increments the base version accordingly\nand print the new version.\n\nIf the current commit type is `release`\nand the `-release` flag\nor `GOTAGGER_RELEASE` environment variable is set,\nthen `gotagger` will tag the current commit with the new version.\nIf there are no commits explicitly marked as a feature or a bug fix,\nthen the patch version is incremented.\n\n\n### Installation\n\nYou can install `gotagger`\nby downloading a pre-built binary for your OS and architecture\nfrom our [releases](https://github.com/sassoftware/gotagger/releases) page.\n\nAlternatively, you can install `gotagger` directly with `go get`.\nIf you go this route,\nwe recommend that you create a \"fake\" module,\nso you can ensure you build a supported release:\n\n```bash\nmkdir tmp\ncd tmp\ngo mod init fake\ngo get github.com/sassoftware/gotagger\n```\n\n\n## Getting started\n\n### Running\n\nRun `gotagger` inside of a git repository to see what the current version is.\n\n```bash\ngit clone https://github.com/sassoftware/gotagger.git\ncd gotagger\nmake build\nbuild/$(go env GOOS)/gotagger\nv0.4.0\n```\n\n**Note**: The version reported may be different,\ndepending on what unreleased changes exist.\n\nTo tag a release,\nmake any changes needed to prepare your project for releasing\n(ie. update the change log,\nmerge any feature branches).\nThen create a \"release\" commit and run gotagger again:\n\n```bash\nVERSION=\"$(gotagger)\"\ngit commit -m \"release: $VERSION\"\ngotagger -release\n```\n\nYou can now perform any release builds,\npush the tag to your central git repository,\nor any other post-release tasks.\n\n`gotagger` can also push any tags it creates,\nby using the `-push` flag.\n\n```bash\ngotagger -release -push\n```\n\n### Configuration\n\nProjects using `gotagger` can control some behaviors via a config file:\n*gotagger.json*.\nCheck out the [gotagger.json](./gotagger.json) in this project\nto see an example configuration.\n\nIf a `gotagger.json` file exists in the working directory,\nGotagger will use it.\nIf no configuration is provided,\nGotagger defaults to the current functionality,\nwhich is equivalent to what is defined in\n[gotagger.json](gotagger.json).\n\nIf you want to place your config file in a non-standard location,\nthen you must use the *-config* flag to tell `gotagger` where it is:\n\n```bash\ngotagger -config path/to/gotagger.json\n```\n\n#### Default Increment\n\nThe *defaultIncrement* option\ncontrols how `gotagger` increments the version\nfor commit types that are not listed in [incrementMappings](#increment-mappings).\nAllowed values are \"minor\", \"patch\", and \"none\".\n\n#### Increment Dirty Worktree\n\nThe *incrementDirtyWorktree* option\ncontrols how `gotagger` increments the version\nwhen there are no new commits,\nbut the worktree is dirty.\nAllowed values are \"minor\", \"patch\", and \"none\".\n\n#### Exclude Modules\n\nThe *excludeModules* option\ncontrols which modules gotagger will attempt to version.\n\n#### Ignore Modules\n\nThe *ignoreModules* option\ntoggles `gotagger` support for [go modules](#go-module-support).\nIf you are using gotagger to version a project written in another language,\nthen set this to \"true\":\n\n```json\n{\n  \"ignoreModules\": true\n}\n```\n\n#### Increment Mappings\n\nThe *incrementMappings* option\ncontrols which part of the semantic version\n`gotagger` increments for a given commit type.\nThis option contains a mapping of commit type to semver increment\nFor example, if your project uses \"f\" for commits that implement features,\nand \"b\" for commits that fix bugs:\n\n```json\n{\n  \"incrementMappings\": {\n    \"f\": \"minor\",\n    \"b\": \"patch\"\n  },\n}\n```\n\n#### Pre-Release Incrementing\n\nThe *incrementPreReleaseMinor* option controls\nhow `gotagger` increments pre-release versions\nfor breaking changes.\nNormally, a breaking change will increment the MAJOR version.\nHowever, for pre-release versions,\nthose with a MAJOR version of \"0\",\nsome projects may want to increment the MINOR version instead.\nThis is done by setting *incrementPreReleaseMinor* to \"true\".\n\n#### Version Prefix\n\nThe *versionPrefix* option controls\nhow `gotagger` prefixes the version it calculates.\nThe default prefix is \"v\", as in \"v2.3.4\".\nSome projects may wish to have no prefix,\nwhich can be done by setting *versionPrefix* to the empty string:\n\n```json\n{\n  \"versionPrefix\": \"\"\n}\n```\n\n**Note**: go has very particular requirements about how tags are named,\nso avoid changing the version prefix if you are versioning a go module.\n\n### Go Module Support\n\nBy default `gotagger` will enforce\n[semantic import versioning](https://github.com/golang/go/wiki/Modules#semantic-import-versioning)\non any project that has one or more `go.mod` files.\nThis means `gotagger` will ignore tags whose major version\ndoes not match the major version of the module,\nas well as tags whose prefix does not match the\npath to the module's `go.mod` file.\n\nFor projects that are not written in go\nbut do have a `go.mod` for build tooling,\nthe `-modules` flag\nand `GOTAGGER_MODULES` environment variable\ncan be used to disable this behavior.\n\n`gotagger` can also tag go multi-module repositories.\nTo tag one ore more modules,\ninclude a `Modules` footer in your commit message\ncontaining a comma-separated list of modules to tag:\n\n```text\nrelease: the bar and baz modules\n\nModules: foo/bar, foo/baz\n```\n\nYou can also use multiple `Modules` footers if you prefer:\n\n```text\nrelease: the bar and baz modules in separate footers\n\nModules: foo/bar\nModules: foo/baz\n```\n\nTo release the \"root\" module explicitly list it in the `Modules` footer:\n\n```text\nrelease: foo and bar\n\nModules: foo, foo/bar\n\n# \"Modules: foo/bar, foo\" also works\n```\n\n`gotagger` will print out all of the versions it tagged\nin the order they are specified in the `Modules` footer.\n\n### Path Filtering\n\n`gotagger` supports versioning individual paths\nwithin a git repository using a path filter.\nCurrently,\nonly a single path filter is supported,\nand `gotagger` will return an error\nif a path filter is used in a repository\nthat contains go modules\nwithout setting `-modules=false`.\n\n## Using gotagger as a library\n\n```go\nimport github.com/sassoftware/gotagger\n```\n\nCreate a Gotagger instance\n\n```go\ng, err := gotagger.New(\"path/to/repo\")\nif err != nil {\n    return err\n}\n\n// get the current version of a repository\nversion, err := g.Version()\nif err != nil {\n    return err\n}\nfmt.Println(\"version:\", version)\n\n// Uncomment this to ignore the module example.com/bar or any modules under some/path\n// g.Config.ExcludeModules = []string{\"example.com/bar\", \"some/path\"}\n\n// get the version of module foo\nfooVersion, err := g.ModuleVersion(\"foo\")\nif err != nil {\n    return err\n}\nfmt.Println(\"foo version:\", fooVersion)\n\n// Check what versions will be tagged.\n// If HEAD is not a release commit,\n// then only the the main module version is returned.\nversions, err := g.TagRepo()\nif err != nil {\n    return err\n}\n\nfor _, v := range versions {\n    fmt.Println(v)\n}\n\n// Create the tags\ng.Config.CreateTag = true\n\n// uncomment to push tags as well\n// g.Config.PushTag = true\n\n_, err := g.TagRepo()\nif err != nil {\n    return err\n}\n```\n\n## Contributing\n\n\u003e We welcome your contributions!\n  Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details\n  on how to submit contributions to this project.\n\n\n## License\n\n\u003e This project is licensed under the [Apache 2.0 License](LICENSE).\n\n[Conventional Commits]: https://www.conventionalcommits.org/en/v1.0.0/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsassoftware%2Fgotagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsassoftware%2Fgotagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsassoftware%2Fgotagger/lists"}