{"id":16987225,"url":"https://github.com/yorickpeterse/clogs","last_synced_at":"2025-03-22T15:30:51.359Z","repository":{"id":204494315,"uuid":"711006745","full_name":"yorickpeterse/clogs","owner":"yorickpeterse","description":"Generate a changelog from Git commits containing trailers","archived":false,"fork":false,"pushed_at":"2025-02-18T16:08:45.000Z","size":70,"stargazers_count":23,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-01T17:11:15.875Z","etag":null,"topics":["changelog","git","inko","trailers"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yorickpeterse.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"yorickpeterse"}},"created_at":"2023-10-28T00:18:58.000Z","updated_at":"2025-02-23T12:15:49.000Z","dependencies_parsed_at":"2023-11-09T01:39:41.733Z","dependency_job_id":"88694120-4b9f-47e8-b294-1c6563980d63","html_url":"https://github.com/yorickpeterse/clogs","commit_stats":null,"previous_names":["yorickpeterse/clogs"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yorickpeterse%2Fclogs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yorickpeterse%2Fclogs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yorickpeterse%2Fclogs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yorickpeterse%2Fclogs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yorickpeterse","download_url":"https://codeload.github.com/yorickpeterse/clogs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244227559,"owners_count":20419261,"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","git","inko","trailers"],"created_at":"2024-10-14T02:48:39.422Z","updated_at":"2025-03-22T15:30:51.352Z","avatar_url":"https://github.com/yorickpeterse.png","language":"Makefile","funding_links":["https://github.com/sponsors/yorickpeterse"],"categories":[],"sub_categories":[],"readme":"# clogs\n\nclogs (short for **c**hange**logs**) is a tool for generating a Markdown\nchangelog, populating the changelog from Git commits containing\n[trailers](https://git-scm.com/docs/git-interpret-trailers). The approach is\nsimilar to that of [GitLab's changelog API](https://docs.gitlab.com/ee/api/repositories.html#add-changelog-data-to-a-changelog-file),\nwhich isn't a coincidence given I implemented said API while working for GitLab.\nUnlike said API, clogs doesn't depend on third-party APIs, and takes a more\nopinionated approach.\n\nCompared to [conventional\ncommits](https://www.conventionalcommits.org/en/v1.0.0/) and the many tools that\nuse the convention, using trailers means you don't have to change how you write\nsubject lines, which is nice if you're trying to stick to a line length of 50\ncharacters (give or take a few). In addition, as Git supports trailers natively,\nyou can filter commits based on these trailers should that ever be necessary.\nYou can also easily add trailers when writing commits by using `git commit\n--trailer=\"Changelog: added\"` for example.\n\n## Usage\n\nclogs only includes commits that contain the `Changelog` trailer. The value of\nthis trailer is the changelog category, as specified in the `changelog.json`\nconfiguration file. Commits without such a trailer are ignored. clogs also\nignores commits that are reverted, provided the bodies of such commit contain\nthe string `This reverts commit SHA` where `SHA` is the SHA of the commit that\nis reverted.\n\nTo generate a changelog for a new version, simply run `clogs VERSION` where\n`VERSION` is the version to generate the changelog for. For more information,\nrun `clogs --help`.\n\n## Configuration\n\nConfiguration settings are specified in a `config.json` file using the following\nformat:\n\n```json\n{\n  \"url\": \"https://github.com/yorickpeterse/clogs/commit/%s\",\n  \"changelog\": \"CHANGELOG.md\",\n  \"categories\": {\n    \"added\": \"Added\",\n    \"fixed\": \"Fixed\",\n    \"changed\": \"Changed\"\n  }\n}\n```\n\nThe `url` pair specifies the project URL, used for generating links to commits.\nThe `%s` placeholder is replaced with the full commit SHA.\n\nThe `changelog` pair specifies the path (relative to the directory of the\nconfiguration file) to the changelog file to update.\n\nThe `categories` object specifies the trailer values (e.g. `added` for\n`Changelog: added`), and the titles to use in the generated changelog section.\nWhen generating the Markdown, commits are grouped in the same order as the\nkey-value pairs in this object (i.e. `added` commits are grouped before `fixed`\ncommits using the above configuration).\n\nTo generate a configuration file and an initial changelog file (if one doesn't\nalready exist), run `clogs init`.\n\n## The output\n\nThe Markdown output is fixed and can't be customized, nor are there any plans\nto add support for this. This is a deliberate, at it keeps the tool simple and\nensures a consistent changelog format.\n\nclogs also requires that the headings for new versions use the format\n`## X.Y.Z ...`, where `X.Y.Z` is a version number and `...` any additional\ncharacters. This format is required such that clogs can figure out where the\nMarkdown for a new version should be inserted, such that the version sections\nare in version order, starting with the newest version. So if your changelog\nlooks like this:\n\n```markdown\n## 2.0.0\n\n...\n\n## 1.1.0\n\n...\n```\n\nAnd you run `clogs 1.2.0`, the result is as follows:\n\n```markdown\n## 2.0.0\n\n...\n\n## 1.2.0\n\n...\n\n## 1.1.0\n\n...\n```\n\nIf no such headings are found, clogs inserts the new section at the end of the\nchangelog.\n\n## Requirements\n\n- Inko 0.18.0 or newer\n- Git\n\nGenerating changelogs comes with the following workflow requirements:\n\n- Commits must include a `Changelog` trailer to be included in the changelog.\n- Tags for releases must be in the format `vMAJOR.MINOR.PATCH`, other formats\n  aren't supported.\n- Release versions passed to clogs must be in the format `MAJOR.MINOR.PATCH`,\n  other formats aren't supported.\n\n## Installation\n\nTo build from source:\n\n```\nmake install PREFIX=~/.local\n```\n\nThis installs the executable into `~/.local/bin/clogs`.\n\nIf you're using Arch Linux, [an AUR\npackage](https://aur.archlinux.org/packages/git-clogs) is also available:\n\n```\nyay -S git-clogs\n```\n\nA Fedora package is available on [copr](https://copr.fedorainfracloud.org/coprs/):\n\n```\nsudo dnf copr enable yorickpeterse/clogs\nsudo dnf install clogs\n```\n\n## License\n\nAll source code in this repository is licensed under the Mozilla Public License\nversion 2.0, unless stated otherwise. A copy of this license can be found in the\nfile \"LICENSE\".\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyorickpeterse%2Fclogs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyorickpeterse%2Fclogs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyorickpeterse%2Fclogs/lists"}