{"id":51242601,"url":"https://github.com/luizjhonata/chlog","last_synced_at":"2026-06-29T01:32:05.546Z","repository":{"id":360698343,"uuid":"1250736305","full_name":"luizjhonata/chlog","owner":"luizjhonata","description":"Fragment-based changelog management for Go and CI/CD pipelines","archived":false,"fork":false,"pushed_at":"2026-06-11T21:54:47.000Z","size":92,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T22:20:02.414Z","etag":null,"topics":["changelog","ci-cd","cicd","cli","devops","go","semver"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/luizjhonata/chlog@v0.1.0","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/luizjhonata.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-26T23:27:04.000Z","updated_at":"2026-06-11T21:53:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/luizjhonata/chlog","commit_stats":null,"previous_names":["luizjhonata/chlog"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/luizjhonata/chlog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luizjhonata%2Fchlog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luizjhonata%2Fchlog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luizjhonata%2Fchlog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luizjhonata%2Fchlog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luizjhonata","download_url":"https://codeload.github.com/luizjhonata/chlog/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luizjhonata%2Fchlog/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34910177,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","ci-cd","cicd","cli","devops","go","semver"],"created_at":"2026-06-29T01:32:04.682Z","updated_at":"2026-06-29T01:32:05.530Z","avatar_url":"https://github.com/luizjhonata.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# chlog\n\n[![CI](https://github.com/luizjhonata/chlog/actions/workflows/default.yaml/badge.svg)](https://github.com/luizjhonata/chlog/actions/workflows/default.yaml)\n[![Release](https://img.shields.io/github/v/release/luizjhonata/chlog)](https://github.com/luizjhonata/chlog/releases/latest)\n[![Go Reference](https://pkg.go.dev/badge/github.com/luizjhonata/chlog.svg)](https://pkg.go.dev/github.com/luizjhonata/chlog)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nFragment-based changelog management for teams. Each change gets its own file — no more merge conflicts on `CHANGELOG.md`.\n\n## Features\n\n- **No merge conflicts** — each PR creates a uniquely-named YAML file instead of editing a shared `CHANGELOG.md`\n- **Keep a Changelog format** — outputs standard `[Unreleased]`, `### Added`, `### Fixed` sections\n- **Automatic version bumps** — infer the next semver version from change kinds (Added → minor, Fixed → patch)\n- **CI gating** — `chlog check` enforces that every PR includes a changelog entry\n- **Git hook** — `chlog hook install` sets up a global pre-commit hook that validates fragments in any chlog-enabled repo\n- **AI assistant integration** — `chlog ai setup` teaches your installed AI assistants to create fragments automatically\n- **Minimal and fast** — single binary, no runtime dependencies\n\n## Why chlog?\n\n- **Six commands** — `new`, `batch`, `merge`, `check`, `hook`, `ai`. Nothing else to learn\n- **Explicit over implicit** — developers write what changed, not structured commit messages\n- **~500 lines of Go** — easy to audit, fork, and contribute\n- **Zero configuration required** — sensible defaults, optional `.chlog.yaml` for customization\n\n## How It Works\n\nInstead of editing `CHANGELOG.md` directly, each PR adds a small YAML fragment to `.changes/unreleased/`. At release time, fragments are compiled into the changelog. This eliminates merge conflicts in multi-developer workflows.\n\n```\n.changes/\n├── unreleased/\n│   ├── 1748359200-a1b2.yaml    # fragment per change\n│   └── 1748359300-c3d4.yaml\n├── v1.0.0.md                   # compiled version file (intermediate)\n└── v1.1.0.md\n```\n\n## Install\n\n### Pre-built binaries\n\nDownload from [GitHub Releases](https://github.com/luizjhonata/chlog/releases/latest). Binaries are available for Linux, macOS, and Windows (amd64/arm64).\n\n### Go install\n\n```bash\ngo install github.com/luizjhonata/chlog@latest\n```\n\n### Build from source\n\n```bash\ngit clone git@github.com:luizjhonata/chlog.git\ncd chlog\nmake install    # builds and copies to ~/.local/bin\n```\n\n## Usage\n\n### Create a fragment\n\n```bash\nchlog new --kind Added --body \"user authentication via OAuth2\"\nchlog new --kind Fixed --body \"null pointer on empty config\"\n```\n\nKind matching is case-insensitive. The fragment is written to `.changes/unreleased/\u003ctimestamp\u003e-\u003crandom\u003e.yaml`.\n\n### Compile fragments into a version file\n\n```bash\nchlog batch 1.0.0   # explicit version\nchlog batch minor   # bump minor from latest\nchlog batch auto    # infer bump from kind→level mapping\n```\n\nThis creates `.changes/v1.0.0.md` with Keep a Changelog format and deletes consumed fragments.\n\nThe base version is resolved from the highest of: existing version files, git tags, and `CHANGELOG.md` headings.\n\nWhile the project is below `1.0.0`, `auto` never graduates to `1.0.0` on its own — a breaking change bumps the minor instead (e.g. `0.2.0` → `0.3.0`), per SemVer's unstable-`0.x` rule. Reaching `1.0.0` is a deliberate, explicit step (`chlog batch major` or `chlog batch 1.0.0`).\n\n### Merge into CHANGELOG.md\n\n```bash\nchlog merge\n```\n\nInserts all version files into `CHANGELOG.md` in descending order, preserving existing content. Deletes consumed version files.\n\n### Verify fragments exist (CI)\n\n```bash\nchlog check\n```\n\nExits 0 if unreleased fragments exist, exits 1 otherwise. Use in CI to enforce that every PR includes a changelog entry.\n\n### Git hook\n\n```bash\nchlog hook install              # global hook (install once, works in every repo)\nchlog hook install --local      # inject into current repo's existing hook (e.g., Husky)\nchlog hook uninstall            # remove global hook\nchlog hook uninstall --local    # remove injected block from current repo\n```\n\n**Global mode (default)** — sets `core.hooksPath` so the hook runs in every repo. Detects `.chlog.yaml` before acting — repos without chlog are unaffected. Chains per-repo hooks automatically so existing hooks keep working.\n\n**Local mode (`--local`)** — appends a chlog block to the current repo's pre-commit hook. Use this when the project already manages hooks via Husky, Lefthook, or similar. The block is injected without modifying existing hook content.\n\n- Idempotent — re-installing when the hook is already present is a no-op\n- Safe — refuses to override an existing `core.hooksPath` unless `--force` is passed\n- `--force` re-installs hooks (useful after a chlog update)\n\n### AI assistant integration\n\n```bash\nchlog ai setup           # inject chlog rules into detected assistants\nchlog ai setup --force   # re-inject the block if it already exists\n```\n\nDetects which AI coding assistants are installed on your machine and injects a\nmandatory changelog rule into the matching project instruction file, so the\nassistant creates fragments automatically whenever you work in a chlog repo.\n\n| Assistant | Detected via | Instruction file |\n|-----------|--------------|------------------|\n| Claude Code | `claude` in `PATH` or `~/.claude/` | `CLAUDE.md` |\n| OpenAI Codex | `codex` in `PATH` or `~/.codex/` | `AGENTS.md` |\n| Cursor | `~/.cursor/` or app config dir | `AGENTS.md` |\n| Gemini CLI | `gemini` in `PATH` or `~/.gemini/` | `GEMINI.md` |\n| GitHub Copilot | `~/.config/github-copilot/` | `.github/copilot-instructions.md` |\n| Windsurf | `~/.windsurf/`, `~/.codeium/windsurf/` or app config dir | `.windsurf/rules/chlog.md` |\n\n- The injected rule is conditional — it only applies in repos that have a `.chlog.yaml`, so it is safe to commit and share\n- Idempotent — the block is delimited by `\u003c!-- chlog:start --\u003e` / `\u003c!-- chlog:end --\u003e` and existing content is preserved\n- If no supported assistant is detected, the command does nothing\n- `--force` re-injects the block (useful after a chlog update)\n\n#### Adding the rule manually\n\nIf detection misses your assistant, or you prefer to set it up by hand, copy the\nblock below into your assistant's instruction file (`CLAUDE.md`, `AGENTS.md`,\n`GEMINI.md`, `.github/copilot-instructions.md`, `.windsurf/rules/chlog.md`, …).\nThe `Valid kinds` line should mirror the `kinds` in your `.chlog.yaml` (the\nvalues below are the defaults).\n\n```markdown\n\u003c!-- chlog:start --\u003e\n## Changelog (chlog) — MANDATORY\n\nIf the repository you are working in uses chlog (a `.chlog.yaml` or `.chlog.yml`\nconfig file, or a `.changes/` directory, exists at the project root), the\nfollowing is binding and ALWAYS applies: whenever you make ANY change, you MUST\ncreate a changelog fragment as part of the same change — automatically, without\nbeing asked, before committing.\n\n- Do NOT edit CHANGELOG.md directly; it is generated from fragments.\n- Create the fragment with:\n  `chlog new --kind \u003cKind\u003e --body \"\u003cimperative description\u003e\"`\n- Valid kinds: Added, Changed, Deprecated, Removed, Fixed, Security\n- Choose the kind that best matches the change (e.g., new feature → Added,\n  bug fix → Fixed, behavior change → Changed, removal → Removed, security fix → Security).\n- Fragments are YAML files in `.changes/unreleased/`; stage them with your commit.\n- `chlog check` fails the build when a fragment is missing — never skip it.\n\u003c!-- chlog:end --\u003e\n```\n\n## Release Flow\n\n```\n1. Developer creates fragments during PR work\n   $ chlog new --kind Added --body \"new feature\"\n\n2. At release time, compile fragments\n   $ chlog batch auto\n\n3. Review the generated version file, then merge\n   $ chlog merge\n\n4. Commit CHANGELOG.md and tag the release\n```\n\n## Configuration\n\nCreate `.chlog.yaml` in your project root. If not found, defaults are used.\n\n```yaml\nchangesDir: .changes\nunreleasedDir: unreleased\nchangelogPath: CHANGELOG.md\nversionFormat: '## [{{.Version}}] - {{.Time.Format \"2006-01-02\"}}'\nkindFormat: '### {{.Kind}}'\nchangeFormat: '- {{.Body}}'\nkinds:\n  - label: Added\n    auto: minor\n  - label: Changed\n    auto: major\n  - label: Deprecated\n    auto: minor\n  - label: Removed\n    auto: major\n  - label: Fixed\n    auto: patch\n  - label: Security\n    auto: patch\n```\n\nThe `auto` field maps each kind to a semver bump level, used by `chlog batch auto`.\n\nFormat fields use Go templates. Available variables:\n\n| Template | Variables |\n|----------|-----------|\n| `versionFormat` | `.Version`, `.Time` |\n| `kindFormat` | `.Kind` |\n| `changeFormat` | `.Body` |\n\n## CI Integration\n\nAdd `chlog check` to your PR pipeline to require a changelog fragment:\n\n```yaml\n# GitHub Actions example\n- name: Verify changelog fragment\n  run: chlog check\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, commit conventions, and code style guidelines.\n\nFound a bug or have a feature request? [Open an issue](https://github.com/luizjhonata/chlog/issues).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluizjhonata%2Fchlog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluizjhonata%2Fchlog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluizjhonata%2Fchlog/lists"}