parser

package

v0.13.0 Latest Latest Go to latest Published: Jul 17, 2026 License: Apache-2.0 Imports: 9 Imported by: 23

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/leodido/go-conventionalcommits

Links

Open Source Insights

Documentation ¶

Overview ¶

SPDX-License-Identifier: Apache-2.0

Example (Best_effort) ¶

i := []byte(`fix: description
a blank line is mandatory to start the body part of the commit message!`)
m, e := NewMachine(WithBestEffort()).Parse(i)
output(m)
fmt.Println(e)

Output:
(*conventionalcommits.ConventionalCommit)({
 Type: (string) (len=3) "fix",
 Description: (string) (len=11) "description",
 Scope: (*string)(<nil>),
 Exclamation: (bool) false,
 Body: (*string)(<nil>),
 Footers: (map[string][]string) <nil>,
 TypeConfig: (conventionalcommits.TypeConfig) 0
})
missing a blank line: col=17

Example (Breaking_freeformtype_with_scope) ¶

i := []byte(`KVM(nVMX)!: Truncate base/index GPR value on address calc in !64-bit`)
m, _ := NewMachine(WithTypes(conventionalcommits.TypesFreeForm)).Parse(i)
output(m)

Output:
(*conventionalcommits.ConventionalCommit)({
 Type: (string) (len=3) "kvm",
 Description: (string) (len=56) "Truncate base/index GPR value on address calc in !64-bit",
 Scope: (*string)((len=4) "nvmx"),
 Exclamation: (bool) true,
 Body: (*string)(<nil>),
 Footers: (map[string][]string) <nil>,
 TypeConfig: (conventionalcommits.TypeConfig) 3
})

Example (Full_conventional) ¶

fixme > flaky because of the footer map keys.

i := []byte(`fix: correct minor typos in code

see the issue [0] for details
on typos fixed.

[0]: https://issue

Reviewed-by: Z
Refs #133`)
opts := []conventionalcommits.MachineOption{
	WithTypes(conventionalcommits.TypesConventional),
}
m, _ := NewMachine(opts...).Parse(i)
output(m)

Output:
(*conventionalcommits.ConventionalCommit)({
 Type: (string) (len=3) "fix",
 Description: (string) (len=27) "correct minor typos in code",
 Scope: (*string)(<nil>),
 Exclamation: (bool) false,
 Body: (*string)((len=65) "see the issue [0] for details\non typos fixed.\n\n[0]: https://issue"),
 Footers: (map[string][]string) (len=2) {
  (string) (len=4) "refs": ([]string) (len=1) {
   (string) (len=3) "133"
  },
  (string) (len=11) "reviewed-by": ([]string) (len=1) {
   (string) (len=1) "Z"
  }
 },
 TypeConfig: (conventionalcommits.TypeConfig) 1
})

Example (Minimal_withoutbody) ¶

i := []byte(`fix!: something`)
m, _ := NewMachine().Parse(i)
output(m)
fmt.Println("there are breaking changes?", m.IsBreakingChange())

Output:
(*conventionalcommits.ConventionalCommit)({
 Type: (string) (len=3) "fix",
 Description: (string) (len=9) "something",
 Scope: (*string)(<nil>),
 Exclamation: (bool) true,
 Body: (*string)(<nil>),
 Footers: (map[string][]string) <nil>,
 TypeConfig: (conventionalcommits.TypeConfig) 0
})
there are breaking changes? true

Example (Multiline_body) ¶

i := []byte(`fix: x

see the issue for details

but first a newline
and then two blank lines:

typos fixed.`)
m, _ := NewMachine().Parse(i)
output(m)

Output:
(*conventionalcommits.ConventionalCommit)({
 Type: (string) (len=3) "fix",
 Description: (string) (len=1) "x",
 Scope: (*string)(<nil>),
 Exclamation: (bool) false,
 Body: (*string)((len=86) "see the issue for details\n\nbut first a newline\nand then two blank lines:\n\ntypos fixed."),
 Footers: (map[string][]string) <nil>,
 TypeConfig: (conventionalcommits.TypeConfig) 0
})

Index ¶

Constants
Variables
func WithBestEffort() conventionalcommits.MachineOption
func WithLogger(l *logrus.Logger) conventionalcommits.MachineOption
func WithTypes(t conventionalcommits.TypeConfig) conventionalcommits.MachineOption
type InvalidUTF8Error
- func (e *InvalidUTF8Error) Error() string
- func (e *InvalidUTF8Error) Unwrap() error
type Machine
- func NewMachine(options ...conventionalcommits.MachineOption) Machine

Examples ¶

Package (Best_effort)
Package (Breaking_freeformtype_with_scope)
Package (Full_conventional)
Package (Minimal_withoutbody)
Package (Multiline_body)

Constants ¶

View Source

const (
	// ErrType represents an error in the type part of the commit message.
	ErrType = "illegal '%s' character in commit message type"
	// ErrTypeIncomplete represents an error when the type part of the commit message is not complete.
	ErrTypeIncomplete = "incomplete commit message type after '%s' character"
	// ErrColon is the error message that communicate that the mandatory colon after the type part of the commit message is missing.
	ErrColon = "expecting colon (':') character, got '%s' character"
	// ErrScope represents an error about illegal characters into the the scope part of the commit message.
	ErrScope = "illegal '%s' character in scope"
	// ErrScopeIncomplete represents a specific early-exit error.
	ErrScopeIncomplete = "expecting closing parentheses (')') character, got early exit after '%s' character"
	// ErrEmpty represents an error when the input is empty.
	ErrEmpty = "empty input"
	// ErrEarly represents an error when the input makes the machine exit too early.
	ErrEarly = "early exit after '%s' character"
	// ErrDescriptionInit tells the user that before of the description part a whitespace is mandatory.
	ErrDescriptionInit = "expecting at least one white-space (' ') character, got '%s' character"
	// ErrDescription tells the user that after the whitespace is mandatory a description.
	ErrDescription = "expecting a description text (without newlines) after '%s' character"
	// ErrNewline communicates an illegal newline to the user.
	ErrNewline = "illegal newline"
	// ErrMissingBlankLineAtBeginning tells the user that the a blank line is missing after the description or after the body.
	ErrMissingBlankLineAtBeginning = "missing a blank line"
	// ErrTrailer represents an error due to an unexepected character while parsing a footer trailer.
	ErrTrailer = "illegal '%s' character in trailer"
	// ErrTrailerIncomplete represent an error when a trailer is not complete.
	ErrTrailerIncomplete = "incomplete footer trailer after '%s' character"
)

Variables ¶

View Source

var ColumnPositionTemplate = ": col=%02d"

ColumnPositionTemplate is the template used to communicate the column where errors occur.

View Source

var ErrInvalidUTF8 = errors.New("invalid UTF-8")

ErrInvalidUTF8 identifies malformed UTF-8 anywhere in the original input.

View Source

var MajorVersion = conventionalcommits.MajorVersion

View Source

var MinorVersion = conventionalcommits.MinorVersion

View Source

var PatchVersion = conventionalcommits.PatchVersion

View Source

var UnknownVersion = conventionalcommits.UnknownVersion

Functions ¶

func WithBestEffort ¶

func WithBestEffort() conventionalcommits.MachineOption

WithBestEffort enables the best effort mode.

Best effort mode tells the parser to return what it found, if the input was a minimally well-formed commit message (type and description part).

func WithLogger ¶

func WithLogger(l *logrus.Logger) conventionalcommits.MachineOption

WithLogger enables a logger during parsing.

func WithTypes ¶

func WithTypes(t conventionalcommits.TypeConfig) conventionalcommits.MachineOption

WithTypes let you choose the types.

Types ¶

type InvalidUTF8Error ¶ added in v0.13.0

type InvalidUTF8Error struct {
	// ByteOffset is the zero-based offset of the first malformed byte.
	ByteOffset int
}

InvalidUTF8Error reports the first malformed byte in the original input.

func (*InvalidUTF8Error) Error ¶ added in v0.13.0

func (e *InvalidUTF8Error) Error() string

func (*InvalidUTF8Error) Unwrap ¶ added in v0.13.0

func (e *InvalidUTF8Error) Unwrap() error

type Machine ¶ added in v0.13.0

type Machine interface {
	conventionalcommits.Machine

	// WithStrictUTF8 requires the entire original input to be well-formed UTF-8.
	// Malformed input returns a nil message and an error at the first invalid byte,
	// including when best effort mode is enabled. The error matches ErrInvalidUTF8
	// and can be inspected as *InvalidUTF8Error.
	WithStrictUTF8()
}

Machine is a Conventional Commits parser with parser-specific configuration.

func NewMachine ¶

func NewMachine(options ...conventionalcommits.MachineOption) Machine

NewMachine creates a new FSM able to parse Conventional Commits.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL