{"id":18310967,"url":"https://github.com/jimschubert/changelog","last_synced_at":"2025-04-05T18:31:46.521Z","repository":{"id":50780577,"uuid":"244037529","full_name":"jimschubert/changelog","owner":"jimschubert","description":"A changelog generator which uses GitHub's API for the details","archived":false,"fork":false,"pushed_at":"2023-12-27T15:07:36.000Z","size":110,"stargazers_count":9,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-21T08:34:58.510Z","etag":null,"topics":["changelog","changelog-generator","github","golang","hacktoberfest"],"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/jimschubert.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.go","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"jimschubert","patreon":"jimschubert"}},"created_at":"2020-02-29T20:34:41.000Z","updated_at":"2024-03-05T04:27:54.000Z","dependencies_parsed_at":"2022-08-24T00:51:21.470Z","dependency_job_id":null,"html_url":"https://github.com/jimschubert/changelog","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimschubert%2Fchangelog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimschubert%2Fchangelog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimschubert%2Fchangelog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimschubert%2Fchangelog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jimschubert","download_url":"https://codeload.github.com/jimschubert/changelog/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247383888,"owners_count":20930365,"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":["changelog","changelog-generator","github","golang","hacktoberfest"],"created_at":"2024-11-05T16:16:03.317Z","updated_at":"2025-04-05T18:31:46.118Z","avatar_url":"https://github.com/jimschubert.png","language":"Go","readme":"# GitHub Changelog Generator\n\n[![Apache 2.0 License](https://img.shields.io/badge/License-Apache%202.0-blue)](./LICENSE)\n![Go Version](https://img.shields.io/github/go-mod/go-version/jimschubert/changelog)\n![Go](https://github.com/jimschubert/changelog/workflows/Go/badge.svg)\n[![Go Report Card](https://goreportcard.com/badge/github.com/jimschubert/changelog)](https://goreportcard.com/report/github.com/jimschubert/changelog)\n![Docker Pulls](https://img.shields.io/docker/pulls/jimschubert/changelog)\n[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=jimschubert_changelog\u0026metric=ncloc)](https://sonarcloud.io/dashboard?id=jimschubert_changelog)\n\nChangelog is a cross-platform changelog generator for GitHub repositories. It queries between any two git branches or tags as supported by the [GitHub Commits API](https://developer.github.com/v3/repos/commits/#compare-two-commits),\nand generates a changelog of commits between the two. It supports [templates](https://golang.org/pkg/text/template/) for those who want more control over generated output.\n\nChangelog's more advanced features support excluding commits from the changelog and grouping commits by heading based on regular expression patterns.\n\n## Usage\n\nA `GITHUB_TOKEN` environment variable must be provided for changelog to operate effectively.\n\n```\nUsage:\n  changelog [OPTIONS]\n\nApplication Options:\n  -o, --owner=   GitHub Owner/Org name (required) [$GITHUB_OWNER]\n  -r, --repo=    GitHub Repo name (required) [$GITHUB_REPO]\n  -f, --from=    Begin changelog from this commit or tag\n  -t, --to=      End changelog at this commit or tag (default: master)\n  -c, --config=  Config file location for more advanced options beyond defaults\n  -l, --local    Prefer local commits when gathering commit logs (as opposed to querying via API)\n      --max=     The maximum number of commits to include\n  -v, --version  Display version information\n\nHelp Options:\n  -h, --help     Show this help message\n```\n\nThe changelog output is written to standard output and can be redirected to overwrite or append to a file.\n\n### Limitations\n\nAs this tool uses GitHub's comparison API for details, there are a few limitations to output:\n\n* Limited to 250 commits\n* Limited to 5000 API requests per hour\n\nSee the [GitHub Commits API](https://developer.github.com/v3/repos/commits/#compare-two-commits) for additional details.\n\n### Basic\n\nThe changelog generator doesn't assume a start or end tag, and doesn't evaluate existing tags to determine tag order. If `from` and `to` options are not provided, your changelog will result in the single latest commit on `master`.\n\nYou may specify `GITHUB_OWNER` and `GITHUB_REPO` as environment variables for use in CI.\n\n#### Examples\n\n**Output for single latest commit on master**\n\n```bash\n./changelog -o jimschubert -r changelog -f master~1 -t master\n```\n\n**Output from some version to latest master**\n\n```bash\n./changelog -o jimschubert -r changelog -f v0.1\n```\n\n**Sample output from one version to another**\n\n```bash\n./changelog -o jimschubert -r kopper -f v0.0.2 -t v0.0.3\n\n## v0.0.3\n\n* [d12243c81d](https://github.com/jimschubert/kopper/commit/d12243c81d6b4b45547929d97e49277d1cae4110) Bump version 0.0.3 ([jimschubert](https://github.com/jimschubert))\n* [41f8fafd25](https://github.com/jimschubert/kopper/commit/41f8fafd25ff336f0de2f16c91ec199aec577843) Support name/description in TypedArgumentParser ([jimschubert](https://github.com/jimschubert))\n* [91b5f02d99](https://github.com/jimschubert/kopper/commit/91b5f02d9918e769493fbeb22fe0ff884ac99b67) Support writing directly to PrintStream ([jimschubert](https://github.com/jimschubert))\n* [ec986bff99](https://github.com/jimschubert/kopper/commit/ec986bff995507c92f10f74b6acae840eb5ab1dc) 0.0.3-SNAPSHOT ([jimschubert](https://github.com/jimschubert))\n\n\n\u003cem\u003eFor more details, see \u003ca href=\"https://github.com/jimschubert/kopper/compare/v0.0.2...v0.0.3\"\u003ev0.0.2..v0.0.3\u003c/a\u003e\u003c/em\u003e\n```\n\n#### Templating\n\nThe default template used in basic usage will output Markdown in flatten or grouped display (see later for configuration options). The template is defined as:\n\n```gotemplate\n{{define \"GroupTemplate\" -}}\n{{- range .Grouped}}\n### {{ .Name }}\n\n{{range .Items -}}\n* [{{.CommitHashShort}}]({{.CommitURL}}) {{.Title}} ({{if .IsPull}}[contributed]({{.PullURL}}) by {{end}}[{{.Author}}]({{.AuthorURL}}))\n{{end -}}\n{{end -}}\n{{end -}}\n{{define \"FlatTemplate\" -}}\n{{range .Items -}}\n* [{{.CommitHashShort}}]({{.CommitURL}}) {{.Title}} ({{if .IsPull}}[contributed]({{.PullURL}}) by {{end}}[{{.Author}}]({{.AuthorURL}}))\n{{end -}}\n{{end -}}\n{{define \"DefaultTemplate\" -}}\n## {{.Version}}\n{{if len .Grouped -}}\n{{template \"GroupTemplate\" . -}}   \n{{- else}}\n{{template \"FlatTemplate\" . -}}\n{{end}}\n\u003cem\u003eFor more details, see \u003ca href=\"{{.CompareURL}}\"\u003e{{.PreviousVersion}}..{{.Version}}\u003c/a\u003e\u003c/em\u003e\n{{end -}}\n{{template \"DefaultTemplate\" . -}}\n```\n\nGroupings will be displayed in the order they're defined in your external configuration.\n\nYou must define an external JSON configuration file to override the default template. For example, suppose you want to display flat commit history and link to diff, patch, and compare URLs. You could define a template like so:\n\n```gotemplate\n## {{.Version}}\n\n{{range .Items -}}\n* [{{.CommitHashShort}}]({{.CommitURL}}) {{.Title}} ({{if .IsPull}}[contributed]({{.PullURL}}) by {{end}}[{{.Author}}]({{.AuthorURL}}))\n{{end}}\n\n### Links\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"{{.CompareURL}}\"\u003eCompare {{.PreviousVersion}}..{{.Version}}\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"{{.DiffURL}}\"\u003eDiff {{.PreviousVersion}}..{{.Version}}\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"{{.PatchURL}}\"\u003ePatch {{.PreviousVersion}}..{{.Version}}\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n```\n\n## Install\n\nLatest binary releases are available via [GitHub Releases](https://github.com/jimschubert/changelog/releases).\n\n### Docker\n\nThe preferred way to run changelog is via Docker. For example:\n\n```bash\ndocker pull jimschubert/changelog:latest\ndocker run -e GITHUB_TOKEN=yourtoken \\\n           -e GITHUB_OWNER=jimschubert \\\n           -e GITHUB_REPO=changelog \\\n   jimschubert/changelog:latest -f v0.1 -t v0.2 \u003e\u003e CHANGELOG.md\n```\n\n### Homebrew\n\n```\nbrew tap jimschubert/tap\nbrew install changelog\n```\n\n## Advanced\n\nMore advanced scenarios require an external JSON configuration object which can be loaded by the `--config` option. The following example properties are supported by the config (comments added inline for brevity):\n\n```json5\n{\n  // \"commits\" or \"prs\", defaults to commits. \"prs\" will soon allow for resolving labels \n  // from pull requests\n  \"resolve\": \"commits\",\n\n  // \"asc\" or \"desc\", determines the order of commits in the output\n  \"sort\": \"asc\",\n  \n  // GitHub user or org name\n  \"owner\": \"jimschubert\",  \n   \n  // Repository name\n  \"repo\": \"changelog\",\n\n  // Enterprise GitHub base url\n  \"enterprise\": \"https://ghe.example.com\",\n\n  // Path to custom template following Go Text template syntax\n  \"template\": \"/path/to/your/template\",\n\n  // Group commits by headings based on patterns supporting Perl syntax regex or plain text\n  \"groupings\": [\n    { \"name\":  \"Contributions\", \"patterns\":  [ \"(?i)\\\\bfeat\\\\b\" ] }\n  ],\n\n  // Exclude commits based on this set of patterns or texts\n  // (useful for common maintenance commit messages)\n  \"exclude\": [\n    \"^(?i)release\\\\s+\\\\d+\\\\.\\\\d+\\\\.\\\\d+\",\n    \"^(?i)minor fix\\\\b\",\n    \"^(?i)wip\\\\b\"\n  ],\n   \n  // Prefers local commits over API. Requires executing from within a Git repository.\n  \"local\": false,\n \n  // Processes UP TO this many commits before processing exclusion/inclusion rules. Defaults to size returned from GitHub API.\n  \"max_commits\": 250\n}\n```\n\n### Custom templating\n\nGrouping is done by the `name` property of the groupings array objects, in the order in which groupings are declared.\nGroupings are displayed by default, but suppose you want to provide a custom template to display grouping differently. In this example, we'll only display the author name if the commit comes from a pull request.\n\nFirst, create a directory at `/tmp/changelog` to contain a sample JSON and template.\n\nSave the follow **template** as `template.tmpl`:\n\n```gotemplate\n## {{.Version}}\n\n{{range .Grouped -}}\n### {{ .Name }}\n\n{{range .Items -}}\n* [{{.CommitHashShort}}]({{.CommitURL}}) {{.Title}}{{if .IsPull}} ([contributed]({{.PullURL}}) by [{{.Author}}]({{.AuthorURL}})){{end}}\n{{end}}\n{{end}}\n\n\u003cem\u003eFor more details, see \u003ca href=\"{{.CompareURL}}\"\u003e{{.PreviousVersion}}..{{.Version}}\u003c/a\u003e\u003c/em\u003e\n```\n\nSave the following as `config.json` (note: template currently requires a full path to the template file):\n\n```json\n{\n  \"sort\": \"desc\",\n  \"template\": \"/tmp/changelog/template.tmpl\",\n  \"groupings\": [\n    {\n      \"name\": \"Fixes\",\n      \"patterns\": [\n        \"(?i)\\\\bbug\\\\b\",\n        \"(?i)\\\\bfix\\\\b\"\n      ]\n    },\n    {\n      \"name\": \"Features\",\n      \"patterns\": [\n        \"^(?i)feat:\\\\b\",\n        \"^(?i)add:\\\\b\"\n      ]\n    },\n    {\n      \"name\": \"Cleanup\",\n      \"patterns\": [\n        \"(?i)\\\\brefactor:\\\\b\"\n      ]\n    },\n    {\n      \"name\": \"Other Contributions\",\n      \"patterns\": [\n        \".?\"\n      ]\n    }\n  ],\n  \"exclude\": [\n    \"(?i)readme\\\\b\",\n    \"(?i)\\\\b\u003e\\\\b\",\n    \"(?i)\\\\btypo\\\\b\",\n    \"^usage$\",\n    \"Bump dependencies\",\n    \"minor\",\n    \"slight\"\n  ]\n}\n```\n\nNow, run this against [cli/cli](https://github.com/cli/cli) v0.5.6 and v0.5.7. Via Docker:\n\n```bash\ndocker run -e GITHUB_TOKEN=yourtoken \\\n   -e GITHUB_OWNER=cli \\\n   -e GITHUB_REPO=cli \\\n   jimschubert/changelog:latest -f v0.5.6 -t v0.5.7 \u003e\u003e /tmp/changelog/CHANGELOG.md\n```\n\nAnd via cli:\n\n```bash\nexport GITHUB_TOKEN=your-token \n./changelog -o cli -r cli -f v0.5.6 -t v0.5.7 \\\n    -c /tmp/changelog/config.json \u003e\u003e /tmp/changelog/CHANGELOG.md\n```\n\nThis changelog output in `/tmp/changelog/CHANGELOG.md` should look like this:\n\n```text\n## v0.5.7\n\n### Fixes\n\n* [f9649ebddd](https://github.com/cli/cli/commit/f9649ebddd1b6a9731046c98cd8019a245c82fde) Merge pull request #521 from yashLadha/bug/issue_list_on_no_remote ([contributed](https://github.com/cli/cli/pull/521) by [mislav](https://github.com/mislav))\n* [4ee995dafd](https://github.com/cli/cli/commit/4ee995dafdf98730c292c63c1b8a0fab5f2198d1) fix(486): Getting issue list on no remotes specified\n* [4c3e498021](https://github.com/cli/cli/commit/4c3e498021997b40d3c78f8c858ed734f819b064) Fix column alignment and truncation for Eastern Asian languages\n\n### Other Contributions\n\n* [b5d0b7c640](https://github.com/cli/cli/commit/b5d0b7c640ad897f395a72074a0f4b31787e5826) Merge pull request #523 from cli/title-body-web ([contributed](https://github.com/cli/cli/pull/523) by [mislav](https://github.com/mislav))\n* [1a82e39ba9](https://github.com/cli/cli/commit/1a82e39ba9627654aca22e9608d5b81589855d41) Respect title \u0026 body from arguments to `pr create -w`\n* [69304ce9af](https://github.com/cli/cli/commit/69304ce9af6100e49bb6a128a81639d48ac590ec) Merge pull request #518 from cli/eastern-asian ([contributed](https://github.com/cli/cli/pull/518) by [mislav](https://github.com/mislav))\n* [4727fc4659](https://github.com/cli/cli/commit/4727fc465982d3029324fc5b77ee37e28c29a2b3) Ensure descriptive error when no github.com remotes found\n\n\n\n\u003cem\u003eFor more details, see \u003ca href=\"https://github.com/cli/cli/compare/v0.5.6...v0.5.7\"\u003ev0.5.6..v0.5.7\u003c/a\u003e\u003c/em\u003e\n```\n\nNotice that this differs from the default in that it removes the committer name from the two commits in each section which were not pull requests.\n\n### Debugging\n\nYou may debug select operations such as groupings and exclusions by exporting `LOG_LEVEL=debug`.\n\n## License\n\nThis project is [licensed](./LICENSE) under Apache 2.0.\n","funding_links":["https://github.com/sponsors/jimschubert","https://patreon.com/jimschubert"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimschubert%2Fchangelog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjimschubert%2Fchangelog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimschubert%2Fchangelog/lists"}