dev-build-deploy / commit-it

Conventional Commits library

CommitIt - Conventional Commits Library

Lightweight (Conventional) Commits library, allowing you to retrieve (Conventional) Commits and verify them against the (Extended) Conventional Commits specification

Features

• Simple to use
• Retrieving commit messages from your git objects or provided string
• Validate the commit message against the (Extended) Conventional Commits specification

Basic Usage

Commit Message

import { Commit } from "@dev-build-deploy/commit-it";

const gitCommit = Commit.fromHash({ hash: "f1aaa6e0b89eb87b591ab623053845b5d5488d9f" });
console.log(JSON.stringify(gitCommit, null, 2))

Conventional Commit message (compliant)

import { ConventionalCommit } from '@dev-build-deploy/commit-it';

// OPTIONAL; Conventional Commits options
const conventionalOptions = {
  // EC-01: A scope MAY be provided after a type. A scope MUST consist of one of the configured values (...) surrounded by parenthesis
  scopes: [ "core", "cli", "action" ],

  // EC-02: Commits MUST be prefixed with a type, which consists of one of the configured values (feat, fix, ...)
  types: [ "build", "ci", "docs", "perf", "refactor", "style", "test" ],
};

const conventionalCommit = ConventionalCommit.fromHash(
  { hash: "f1aaa6e0b89eb87b591ab623053845b5d5488d9f" },
  conventionalOptions
);

// NOTE: See "Non-compliant Conventional Commits message" for details on how to capture failures.
console.log(JSON.stringify(conventionalCommit, null, 2));

Output...

{
  "hash": "f1aaa6e0b89eb87b591ab623053845b5d5488d9f",
  "author": {
    "name": "Kevin de Jong <[email protected]>",
    "date": "2023-06-19T04:20:03.000Z"
  },
  "committer": {
    "name": "Kevin de Jong <[email protected]>",
    "date": "2023-06-19T04:20:03.000Z"
  },
  "subject": "feat: mark Conventional Commit as 'breaking' in case specified in the footer",
  "body": "A Conventional Commit must be marked as a BREAKING change when:\n- An exlamantion mark (`!`) is used in the subject\n- The footer contains either `BREAKING-CHANGE: xyz` or `BREAKING CHANGE: xyz`\n\nThis commit adds the second use case.",
  "footer": {
    "Implements": "#6"
  },
  "type": "feat",
  "breaking": false,
  "description": "mark Conventional Commit as 'breaking' in case specified in the footer",
  "validation": {
    "isValid": true,
    "errors": [],
    "warnings": []
  }
}

Conventional Commit message (non-compliant)

import { ConventionalCommit } from '@dev-build-deploy/commit-it';

// Provide a commit message as a string
const conventionalCommit = ConventionalCommit.fromString({
  hash: "0ab1cd2ef",
  message: "feat (no noun): non-compliant conventional commits message",
});

if (!conventionalCommit.isValid) {
  conventionalCommit.errors.forEach(e => console.log(e.toString()));
}

Output...

Contributing

If you have suggestions for how commit-it could be improved, or want to report a bug, open an issue! We'd love all and any contributions.

For more, check out the Contributing Guide.

License

• MIT © 2023 Kevin de Jong <[email protected]>
• CC-BY-3.0 © 2023 Free Software Foundation Europe e.V.

commit-it's Issues

Add support for BREAKING[- ]CHANGE

Context

Currently, a Conventional Commit is only marked as "breaking" in cases where the user added a ! in the commit subject, i.e.:

feat!: this is a breaking change

However, the Conventional Commits specification also allows users to provide a git-trailer in the footer;

feat: this is a breaking change

BREAKING-CHANGE: description of the breaking change

NOTE: The specification allowes the usage of BREAKING CHANGE (without -) as well.

Proposal

• Implement support for breaking down the commit message's footer into key-value pairs
• Mark a Conventional Commit as breaking in all above use cases.

Merging a remote branch results in an error

Commit message (created by GitHub):

Merge remote-tracking branch 'origin/develop' into feature/...

Commit message validation fail:

error: Commits MUST be prefixed with a type, which consists of a noun, feat, fix, etc., followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space.

Ignore comments on the commit message

I think comments (lines starting with #) should be ignored by the parser.

➜ echo -e "foo: bar\n# comment" > MSG ; python -mpre_commit hook-impl --config=.pre-commit-config.yaml --hook-type=commit-msg --hook-dir /var/tmp/tmp.WtDrdMZqn8/.git/hooks -- MSG
CommitMe - Conventional Commit message validation........................Failed
- hook id: commit-me
- exit code: 1

(node:724770) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
HEAD:1:0: error: Commits MUST be prefixed with a type, which consists of a noun, feat, fix, etc., followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space.

  1 | foo: bar
# comment
    | ^

HEAD:1:0: error: Commits MUST be prefixed with a type, which consists of a noun, feat, fix, etc., followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space.

  1 | foo: bar
# comment
    | ^

❌ Found 2 Conventional Commit compliance issues.

Extend Commit metadata with fixup and merge attributes

Context

Currently, the validator will fail on fixup! and Merge branch [..] into [..] commit messages. Although this is theoretically correct, we would want to allow the client to filter both message types before running validation.

Proposal

Extend the commit metadata with fixup: boolean and merge: boolean attributes.