simple-commitlint

commitlint, but in simpler ✨

how to use

1. npm i -D simple-commitlint / yarn -D simple-commitlint
2. create a config file simple-commitlintrc with one of the following extensions: js, ts, mjs, json, yml/yaml

plain configuration

(taken from types.ts, for further details check it out)

interface Config {
  /**
   * prepare the commit by providing an own logic to separate title and body (return a string if it's an invalid commit to prepare)
   * by default it's title = row[0], body = otherRows
   */
  prepareCommit?: (raw: string) => Pick<Commit, 'title' | 'body'> | string;
  /** an array of rules (which must have a name and a validation), if left empty the linter exits with code 0 */
  rules?: Array<Rule>;
  /** set to true if you want to exit on an already existing non-zero exit code (it's simply forwarded) */
  forwardExitCode?: boolean;
}

It's recommended to use js/ts files in combination with the exported defineConfig function for autocompletion and more flexibility. Create a simple-commitlintrc.js f.e. like this

  // simple-commitlintrc.js
  import { defineConfig } from 'simple-commitlint/helpers'

  // -------------------
  // and ONE of the following possibilities
  // -------------------

  // possibility 1 (object within)
  export default defineConfig({ ... })

  // possibility 2 (function that returns an object within)
  export default defineConfig(() => ({ ... }))

  // possibility 3 (function that returns a promise with the object within)
  export default defineConfig(async () => ({ ... }))

usage

parameters

| name | purpose | | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | --git | the path for the COMMIT_EDITMSG | | --params | params to pass to validation functions | | --config | use a different name than simple-commitlintrc (name should be provided without extension, still allows all extensions then!) |

husky

Most likely you'll use this with husky. For that purpose setup husky and run npx husky add .husky/commit-msg "npx --no-install simple-commitlint --git $1" (pretty similar to the use of husky with the original commitlint).

simple example rules

defineConfig({
  rules: [
    {
      name: 'head-not-empty',
      valid({ title }) {
        return title.length > 0;
      },
    },
  ],
});

defineConfig({
  rules: [
    {
      name: 'body-not-directly-under-head',
      valid({ body }) {
        return body.split('\n')[0].trim().length === 0;
      },
    },
  ],
});

defineConfig({
  rules: [
    {
      name: 'jira',
      valid({ title }) {
        return /^[A-Z]+-\d+ ?(?:\/\/?|:) ?[^\/ ].*$/.test(title);
      },
    },
  ],
});

(required to add params, example within .husky/commit-msg)

  npx simple-commitlint --git $1 --params "$(git diff --name-only)"

defineConfig({
  rules: [
    {
      name: 'special-case',
      valid({ title, cli }) {
        if (cli.split('\n').some((path) => path.endsWith('fileABC.ts')))
          return /someSpecialTest/.test(title);

        return /defaultTest/.test(title);
      },
    },
  ],
});

upcoming

• more examples (maybe on a separate page)
• more flexibility (prolly giving prepareCommit more power)
• improvements of the CLI output
• ...