{"id":27136327,"url":"https://github.com/niclasvaneyk/keepac","last_synced_at":"2025-06-21T11:06:01.692Z","repository":{"id":167990513,"uuid":"642580511","full_name":"NiclasvanEyk/keepac","owner":"NiclasvanEyk","description":"📜 A command line tool for working with changelogs","archived":false,"fork":false,"pushed_at":"2025-04-26T21:08:27.000Z","size":292,"stargazers_count":4,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-26T22:19:11.324Z","etag":null,"topics":["changelog","cli","keep-a-changelog","plaintext","tui"],"latest_commit_sha":null,"homepage":"","language":"Go","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/NiclasvanEyk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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,"zenodo":null}},"created_at":"2023-05-18T22:36:03.000Z","updated_at":"2024-12-01T20:48:21.000Z","dependencies_parsed_at":"2024-02-11T17:24:29.147Z","dependency_job_id":"7d4b00d6-c07b-4932-8981-0962895dd360","html_url":"https://github.com/NiclasvanEyk/keepac","commit_stats":null,"previous_names":["niclasvaneyk/keepac"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/NiclasvanEyk/keepac","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NiclasvanEyk%2Fkeepac","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NiclasvanEyk%2Fkeepac/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NiclasvanEyk%2Fkeepac/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NiclasvanEyk%2Fkeepac/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NiclasvanEyk","download_url":"https://codeload.github.com/NiclasvanEyk/keepac/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NiclasvanEyk%2Fkeepac/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261110603,"owners_count":23111063,"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","cli","keep-a-changelog","plaintext","tui"],"created_at":"2025-04-08T02:04:41.299Z","updated_at":"2025-06-21T11:05:56.655Z","avatar_url":"https://github.com/NiclasvanEyk.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `keepac`\n\nAn opiniated way of managing changelogs adhering to the [keepachangelog](https://keepachangelog.com/) guidelines.\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://niclasvaneyk.github.io/keepac/demo.dark.gif\"\u003e\n  \u003cimg src=\"https://niclasvaneyk.github.io/keepac/demo.light.gif\" loading=\"lazy\"\u003e\n\u003c/picture\u003e\n\n## Installation\n\n### Homebrew\n\nThe preferred method, since you receive updates via `brew update` and it works on MacOS, Linux and WSL.\nShell completions are installed automatically, so tabbing for command or argument completions just works.\n\n```shell\nbrew install niclasvaneyk/keepac/keepac\n```\n\n\u003e Note: You likely need to open a new shell instance after the installation succeeds in order for the completions to work properly\n\n### Other\n\nPre-built binaries and bundles can be downloaded from the [GitHub Releases Page](https://github.com/NiclasvanEyk/keepac/releases).\nIt contains `.deb`, `.rpm`, `.exe` and other formats for a variety of CPU architectures.\nThese do not get automatic updates and depending on the format you may need to install the shell completions yourself.\n\nIf you are not able to download and install a pre-built version, you may build one yourself by cloning this repository and running `go build -o changelog`.\n\n## Usage\n\nWriting changelogs is not rocket science, but the process definitely feels more manual than other workflows.\n\n1. You need to find the `CHANGELOG.md` in your project and open it in your editor:\n\n   ```markdown\n   # Changelog\n\n   ## [2.3.4] - 2023-06-06\n\n   ...\n   ```\n\n2. You then create a new section for the next release\n\n   ```diff\n   # Changelog\n\n   + ## [Unreleased]\n\n   ## [2.3.4] - 2023-06-06\n\n   ...\n   ```\n\n3. another one for bug fixes\n\n   ```diff\n   # Changelog\n\n   ## [Unreleased]\n\n   + ### Fixed\n\n   ## [2.3.4] - 2023-06-06\n\n   ...\n   ```\n\n4. and finally document your fix:\n\n   ```diff\n   # Changelog\n\n   ## [Unreleased]\n\n   ### Fixed\n\n   + - A bug that lead to X when doing Y\n\n   ## [2.3.4] - 2023-06-06\n\n   ...\n   ```\n\n5. then you save the document, close your editor and you are done.\n\nPresenting this as a list makes it look like more effort than it actually is, but each step requires tiny ammounts of mental effort and could prevent someone from keeping a changelog.\n\nWith `keepac` you could have done all of this by running\n\n```shell\nchangelog fixed \"A bug that lead to X when doing Y\"\n```\n\ninside your terminal, similar to how you would do it with `git`.\n\nMissing sections are added on-demand and sections are always added in the same order.\nIt can be run from anywhere inside your project, since it recursively searches upward the directory tree for a `CHANGELOG.md` file.\nLess thinking _how_ to do something and more focus on the _what_.\n\n## Reference\n\n### Reading\n\n#### `changelog find`\n\nFinds the nearest `CHANGELOG.md` relative to the current working directory and prints it to the console.\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://niclasvaneyk.github.io/keepac/find.dark.gif\"\u003e\n  \u003cimg src=\"https://niclasvaneyk.github.io/keepac/find.light.gif\" loading=\"lazy\"\u003e\n\u003c/picture\u003e\n\nIf none is found, keepac will recursively walk upwards the directory tree until it either reaches the root or finds one.\n\n\u003e Note: \"The nearest changelog\" will be used throughout this readme to refer to this upward search for `CHANGELOG.md` files.\n\nWhile quite basic, this command can be used in conjunction with other tools to quickly build custom functionality.\n\n#### `changelog show`\n\nRenders the nearest changelog right inside your terminal using [charmbracelet/glamour](https://github.com/charmbracelet/glamour).\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://niclasvaneyk.github.io/keepac/show.dark.gif\"\u003e\n  \u003cimg src=\"https://niclasvaneyk.github.io/keepac/show.light.gif\" loading=\"lazy\"\u003e\n\u003c/picture\u003e\n\n\u003e Since keepac uses `glamour` to render markdown, you can theme its output by setting the `GLAMOUR_STYLE` environment variable to one of the [available styles](https://github.com/charmbracelet/glamour/tree/master/styles/gallery) or [create your own](https://github.com/charmbracelet/glamour/tree/master/styles).\n\n#### `changelog search`\n\nSearches for changes matching the given search query.\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://niclasvaneyk.github.io/keepac/search.dark.gif\"\u003e\n  \u003cimg src=\"https://niclasvaneyk.github.io/keepac/search.light.gif\" loading=\"lazy\"\u003e\n\u003c/picture\u003e\n\nMatches are displayed with contextual information, such as the version the change was released in and its type of change.\n\n### Writing\n\n#### `changelog init`\n\nCreates an empty `CHANGELOG.md` file in the current directory which looks something like this:\n\n```markdown\n# Changelog\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n## [Unreleased]\n\n### Added\n```\n\n#### `changelog edit`\n\nOpens the nearest changelog inside your `$EDITOR`.\n\nIf you did not set the `$EDITOR` environment variable, commands like `xdg-open` or `open` are used as a fallback.\n\n#### `changelog insert`\n\nAdds a new entry to one of your sections in the changelog.\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://niclasvaneyk.github.io/keepac/insert.dark.gif\"\u003e\n  \u003cimg src=\"https://niclasvaneyk.github.io/keepac/insert.light.gif\" loading=\"lazy\"\u003e\n\u003c/picture\u003e\n\nNow we arrive at the more useful features of keepac.\nMost of the edits to your changelog are additive and will most likely touch the next release.\nThis is why the keepachangelog guidelines suggest keeping the `[Unreleased]` section right at the top, so you don't have to scroll all the way to the bottom.\n\nBy default we assume you want to add to the next release, so running\n\n```shell\nchangelog insert\n```\n\nwill open up either your `$EDITOR` or an inline one if the `$EDITOR` environment variable is not set.\nDescribe your changes, close the editor and an entry .\n\n#### `changelog release`\n\nTurns the `[Unreleased]` section into a proper versioned release.\n\nYou may pass a version adhering to SemVer or use the `--major`, `--minor`, `--patch` flags.\nNote that there must be prior releases in order to use these!\nBy default the current date is used as the realease date, but you may override this using the `--date` option.\n\n#### `changelog yank \u003cversion\u003e`\n\nMarks the specified released as yanked. To cite [Keep a Changelog](https://keepachangelog.com/en/1.1.0/#yanked):\n\n\u003e Yanked releases are versions that had to be pulled because of a serious bug or security issue. Often these versions don't even appear in change logs. They should. This is how you should display them:\n\u003e\n\u003e ```markdown\n\u003e ## [0.0.5] - 2014-12-13 [YANKED]\n\u003e ```\n\u003e\n\u003e The [YANKED] tag is loud for a reason. It's important for people to notice it. Since it's surrounded by brackets it's also easier to parse programmatically.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniclasvaneyk%2Fkeepac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniclasvaneyk%2Fkeepac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniclasvaneyk%2Fkeepac/lists"}