README
¶
changelog
A Go library for parsing changelog files into structured entries. Supports Keep a Changelog, markdown header, and setext/underline formats with automatic detection.
Port of the Ruby changelog-parser gem.
Installation
go get github.com/git-pkgs/changelog
Usage
Parse a string
p := changelog.Parse(content)
for _, v := range p.Versions() {
entry, _ := p.Entry(v)
fmt.Printf("%s (%v): %s\n", v, entry.Date, entry.Content)
}
Parse a file
p, err := changelog.ParseFile("CHANGELOG.md")
Find and parse a changelog in a directory
p, err := changelog.FindAndParse(".")
Searches for common changelog filenames (CHANGELOG.md, NEWS, CHANGES, HISTORY, etc.) and parses the first match.
Specify format explicitly
p := changelog.ParseWithFormat(content, changelog.FormatKeepAChangelog)
p := changelog.ParseWithFormat(content, changelog.FormatMarkdown)
p := changelog.ParseWithFormat(content, changelog.FormatUnderline)
Custom regex pattern
pattern := regexp.MustCompile(`^Version ([\d.]+) released (\d{4}-\d{2}-\d{2})`)
p := changelog.ParseWithPattern(content, pattern)
The first capture group is the version string. An optional second capture group is parsed as a date (YYYY-MM-DD).
Get content between versions
content, ok := p.Between("1.0.0", "2.0.0")
Fetch and parse from a repository URL
p, err := changelog.FetchAndParse(ctx, "https://github.com/owner/repo", "CHANGELOG.md")
Constructs a raw content URL (GitHub and GitLab are supported), fetches the file, and parses it.
You can also build the raw URL yourself:
url, err := changelog.RawContentURL("https://github.com/owner/repo", "CHANGELOG.md")
// "https://raw.githubusercontent.com/owner/repo/HEAD/CHANGELOG.md"
Find line number for a version
line := p.LineForVersion("1.0.0") // 0-based, -1 if not found
Supported formats
Keep a Changelog (## [1.0.0] - 2024-01-15):
## [Unreleased]
## [1.1.0] - 2024-03-15
### Added
- New feature
## [1.0.0] - 2024-01-15
- Initial release
Markdown headers (## 1.0.0 (2024-01-15) or ### v1.0.0):
## 2.0.0 (2024-03-01)
- Breaking changes
## 1.5.0
- New features
Setext/underline (version with === or --- underline):
3.0.0
=====
Major release.
2.1.0
-----
Minor release.
License
MIT
Documentation
¶
Overview ¶
Package changelog parses changelog files into structured entries.
It supports three common formats: Keep a Changelog (## [version] - date), markdown headers (## version or ### version), and setext/underline style (version\n=====). Format detection is automatic by default.
Basic usage:
p := changelog.Parse(content)
for _, v := range p.Versions() {
entry, _ := p.Entry(v)
fmt.Printf("%s: %s\n", v, entry.Content)
}
Parse a file:
p, err := changelog.ParseFile("CHANGELOG.md")
Find and parse a changelog in a directory:
p, err := changelog.FindAndParse(".")
Index ¶
- func FindChangelog(directory string) (string, error)
- func RawContentURL(repoURL, filename string) (string, error)
- type Entry
- type Format
- type Parser
- func FetchAndParse(ctx context.Context, repoURL, filename string) (*Parser, error)
- func FindAndParse(directory string) (*Parser, error)
- func Parse(content string) *Parser
- func ParseFile(path string) (*Parser, error)
- func ParseWithFormat(content string, format Format) *Parser
- func ParseWithPattern(content string, pattern *regexp.Regexp) *Parser
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FindChangelog ¶
FindChangelog locates a changelog file in the given directory. Returns the path to the changelog file, or empty string if not found.
func RawContentURL ¶ added in v0.1.1
RawContentURL constructs a URL that serves the raw content of a file in a repository. Supports GitHub and GitLab. The repoURL should be the repository's web URL (e.g. "https://github.com/owner/repo"). Trailing ".git" suffixes and slashes are stripped automatically.
Types ¶
type Parser ¶
type Parser struct {
// contains filtered or unexported fields
}
Parser holds the parsed changelog data and provides access methods.
func FetchAndParse ¶ added in v0.1.1
FetchAndParse fetches a changelog from a repository and parses it. It constructs the raw content URL from the repository URL and changelog filename, fetches the content over HTTP, and returns a Parser.
func FindAndParse ¶
FindAndParse locates a changelog file in the directory and parses it.
func ParseWithFormat ¶
ParseWithFormat creates a parser using the specified format.
func ParseWithPattern ¶
ParseWithPattern creates a parser using a custom regex pattern. The pattern must have at least one capture group for the version string. An optional second capture group captures the date (YYYY-MM-DD). The (?m) flag is automatically added if not already present, so that ^ and $ match line boundaries.
func (*Parser) Between ¶
Between returns the content between two version headers. Either version can be empty to indicate the start or end of the changelog. Returns the content and true if found, or empty string and false if not.
func (*Parser) Entries ¶
Entries returns all entries as a map. Note that Go maps do not preserve insertion order; use Versions() + Entry() if order matters.
func (*Parser) LineForVersion ¶
LineForVersion returns the 0-based line number where the given version header appears, or -1 if not found. Strips a leading "v" prefix for matching.
Source Files