Conventional commits

cog commit allows you to easily create commits respecting the conventional commits specification. It comes with a set of predefined arguments named after conventional commit types and Angular commit convention : (feat, fix, style, build, refactor, ci, test, perf, chore, revert, docs).

As described in the specification conventional commits messages are structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

All cog commit type subcommands follow the same structure:

cog commit [FLAGS] <type> <message> [scope]

Note that the commit scope comes after the commit description. This allows using positional arguments instead of typing a scope flag every time.

Example:

If you want to create the following commit: feat: add awesome feature:

# With cog
cog commit feat "add awesome feature"

# With git
git commit -m "feat: add awesome feature"

Helpful error messages

Using cog commit should prevent a wide range of error in your conventional commit message. But if you still made a mistake, cog will display an error explaining what went wrong:

❯ cog commit feat "add ability to parse arrays" "sco(pe"
Error: A scope value cannot contains inner parenthesis

Caused by:
     --> 1:9
      |
    1 | feat(sco(pe): add ability to parse arrays
      |         ^---
      |
      = expected no_parenthesis

Breaking changes

All cog commit arguments are positional except the optional -B flag used to create breaking changes commits:

cog commit fix -B "add fix a nasty bug" cli

This would create the following breaking change commit: fix(cli)!: fix a nasty bug.

cog commit use the ! notation to denote breaking changes commit because it can be easily seen in your git log, however if you manually create breaking changes commits with the footer notation cocogitto tools will still pick them.

Commit Body and footers

If you need to create more complex commit messages with body and footers use the --edit flag.

Example:

cog commit refactor -e -B "drop support for Node 6" runtime

This would open the following commit message template in your $EDITOR of choice:

# Enter the commit message for your changes.
# Lines starting with # will be ignored, and empty body/footer are allowed.
# Once you are done, save the changes and exit the editor.
# Remove all non-comment lines to abort.
#
# WARNING: This will be marked as a breaking change!
refactor(runtime): drop support for Node 6

# Message body


# Message footer
# For example, foo: bar

Upon save a commit will be created with the body and footer typed.

TIP

There are two kinds of footer separators in conventional commits: token: message and token #message.

GitHub automatically link issues prefixed with a hash.

Example:

    feat(changelog): add full_hash changelog template

    Closes #127

Custom commit types

Allowing custom commit types: By default cog commit supports standard conventional commits type feat, fix plus the angular commit types: build, ci, revert, docs, test, style, chore, perf. If you want to use more types you can add them to a file named cog.toml in your repository root directory:

[commit_types]
hotfix = { changelog_title = "Hotfixes" }
release = { changelog_title = "Releases" }

The above config would generate a cog commit hotfix and cog commit release subcommands following the same structure as the default ones.

Overriding existing commit types:

Existing commit type can be overridden just like custom ones:

[commit_types]
feat = { changelog_title = "➕ Additional features" }
fix = { changelog_title = "🪲 Releases" }

Omit commits from changelog:

If you want to make changelog more concise you can skip some commit types with the omit_from_changelog option.

[commit_types]
chore = { changelog_title = "", omit_from_changelog = true }
ci = { changelog_title = "", omit_from_changelog = true }
perf = { changelog_title = "", omit_from_changelog = true }

Change the auto-bump behavior for a commit_type: [commit_types] build =

Disabling default commit types:

While active by default, you can disable any of the default commit types by providing an empty configuration:

[commit_types]
perf = {}

Deal with merge commits

By default, git will write the following message to merge commit: Merge my 'branch'. These merge commits do not respect the Conventional Commits specification, and we strongly advise avoiding them by setting the following in your .gitconfig:

[merge]
  ff = only

That said you can simply make Cocogitto ignore merge commits by setting the following in your cog.toml:

ignore_merge_commits = true