fix(cli): add environment variable cli flag (#343)

fixes #319.

additionally fixes some minor typos in docs

Author: DJMcNab

@commitlint/cli/src/cli.js

@@ -40,14 +40,22 @@ const flags = {
 			'read last commit message from the specified file or fallbacks to ./.git/COMMIT_EDITMSG',
 		type: 'string'
 	},
+	env: {
+		alias: 'E',
+		default: null,
+		description:
+			'check message in the file at path given by environment variable value',
+		type: 'string'
+	},
 	extends: {
 		alias: 'x',
 		description: 'array of shareable configurations to extend',
 		type: 'string'
 	},
 	help: {
 		alias: 'h',
-		type: 'boolean'
+		type: 'boolean',
+		description: 'display this help message'
 	},
 	from: {
 		alias: 'f',
@@ -74,14 +82,15 @@ const flags = {
 	},
 	version: {
 		alias: 'v',
-		type: 'boolean'
+		type: 'boolean',
+		description: 'display version information'
 	}
 };
 
 const cli = meow({
 	description: `${pkg.name}@${pkg.version} - ${pkg.description}`,
 	flags,
-	help: `[input] reads from stdin if --edit, --from and --to are omitted\n${help(
+	help: `[input] reads from stdin if --edit, --env, --from and --to are omitted\n${help(
 		flags
 	)}`,
 	unknown(arg) {
@@ -114,7 +123,7 @@ async function main(options) {
 
 	if (messages.length === 0 && !checkFromRepository(flags)) {
 		const err = new Error(
-			'[input] is required: supply via stdin, or --edit or --from and --to'
+			'[input] is required: supply via stdin, or --env or --edit or --from and --to'
 		);
 		err.type = pkg.name;
 		console.log(`${cli.help}\n`);
@@ -165,29 +174,48 @@ function checkFromRepository(flags) {
 }
 
 function checkFromEdit(flags) {
-	return Boolean(flags.edit);
+	return Boolean(flags.edit) || flags.env;
 }
 
 function checkFromHistory(flags) {
 	return typeof flags.from === 'string' || typeof flags.to === 'string';
 }
 
 function normalizeFlags(flags) {
-	// The `edit` flag is either a boolean or a string but we are only allowed
-	// to specify one of them in minimist
-	const edit = flags.edit === '' ? true : normalizeEdit(flags.edit);
+	const edit = getEditValue(flags);
 	return merge({}, flags, {edit, e: edit});
 }
 
-function normalizeEdit(edit) {
+function getEditValue(flags) {
+	if (flags.env) {
+		if (!(flags.env in process.env)) {
+			throw new Error(
+				`Recieved '${
+					flags.env
+				}' as value for -E | --env, but environment variable '${
+					flags.env
+				}' is not available globally`
+			);
+		}
+		return process.env[flags.env];
+	}
+	const edit = flags.edit;
+	// If the edit flag is set but empty (i.e '-e') we default
+	// to .git/COMMIT_EDITMSG
+	if (edit === '') {
+		return true;
+	}
 	if (typeof edit === 'boolean') {
 		return edit;
 	}
-	// The recommended method to specify -e with husky is commitlint -e $GIT_PARAMS
+	// The recommended method to specify -e with husky was `commitlint -e $GIT_PARAMS`
 	// This does not work properly with win32 systems, where env variable declarations
 	// use a different syntax
 	// See https://github.com/marionebl/commitlint/issues/103 for details
+	// This has been superceded by the `-E GIT_PARAMS` / `-E HUSKY_GIT_PARAMS`
 	if (edit === '$GIT_PARAMS' || edit === '%GIT_PARAMS%') {
+		console.warn(`Using environment variable syntax (${edit}) in -e |\
+--edit is deprecated. Use '{-E|--env} GIT_PARAMS instead'`);
 		if (!('GIT_PARAMS' in process.env)) {
 			throw new Error(
 				`Received ${edit} as value for -e | --edit, but GIT_PARAMS is not available globally.`

@commitlint/cli/src/cli.test.js

@@ -92,7 +92,7 @@ test('should produce no error output with -q flag', async t => {
 
 test('should work with husky commitmsg hook and git commit', async () => {
 	const cwd = await git.bootstrap('fixtures/husky/integration');
-	await writePkg({scripts: {commitmsg: `${bin} -e`}}, {cwd});
+	await writePkg({scripts: {commitmsg: `'${bin}' -e`}}, {cwd});
 
 	await execa('npm', ['install'], {cwd});
 	await execa('git', ['add', 'package.json'], {cwd});
@@ -102,7 +102,7 @@ test('should work with husky commitmsg hook and git commit', async () => {
 test('should work with husky commitmsg hook in sub packages', async () => {
 	const upper = await git.bootstrap('fixtures/husky');
 	const cwd = path.join(upper, 'integration');
-	await writePkg({scripts: {commitmsg: `${bin} -e`}}, {cwd: upper});
+	await writePkg({scripts: {commitmsg: `'${bin}' -e`}}, {cwd: upper});
 
 	await execa('npm', ['install'], {cwd});
 	await execa('git', ['add', 'package.json'], {cwd});
@@ -111,7 +111,7 @@ test('should work with husky commitmsg hook in sub packages', async () => {
 
 test('should work with husky via commitlint -e $GIT_PARAMS', async () => {
 	const cwd = await git.bootstrap('fixtures/husky/integration');
-	await writePkg({scripts: {commitmsg: `${bin} -e $GIT_PARAMS`}}, {cwd});
+	await writePkg({scripts: {commitmsg: `'${bin}' -e $GIT_PARAMS`}}, {cwd});
 
 	await execa('npm', ['install'], {cwd});
 	await execa('git', ['add', 'package.json'], {cwd});
@@ -120,13 +120,37 @@ test('should work with husky via commitlint -e $GIT_PARAMS', async () => {
 
 test('should work with husky via commitlint -e %GIT_PARAMS%', async () => {
 	const cwd = await git.bootstrap('fixtures/husky/integration');
-	await writePkg({scripts: {commitmsg: `${bin} -e %GIT_PARAMS%`}}, {cwd});
+	await writePkg({scripts: {commitmsg: `'${bin}' -e %GIT_PARAMS%`}}, {cwd});
 
 	await execa('npm', ['install'], {cwd});
 	await execa('git', ['add', 'package.json'], {cwd});
 	await execa('git', ['commit', '-m', '"test: this should work"'], {cwd});
 });
 
+test('should allow reading of environment variables for edit file, succeeding if valid', async t => {
+	const cwd = await git.bootstrap();
+	await sander.writeFile(cwd, 'commit-msg-file', 'foo');
+	const actual = await cli(['--env', 'variable'], {
+		cwd,
+		env: {variable: 'commit-msg-file'}
+	})();
+	t.is(actual.code, 0);
+});
+
+test('should allow reading of environment variables for edit file, failing if invalid', async t => {
+	const cwd = await git.bootstrap('fixtures/simple');
+	await sander.writeFile(
+		cwd,
+		'commit-msg-file',
+		'foo: bar\n\nFoo bar bizz buzz.\n\nCloses #123.'
+	);
+	const actual = await cli(['--env', 'variable'], {
+		cwd,
+		env: {variable: 'commit-msg-file'}
+	})();
+	t.is(actual.code, 1);
+});
+
 test('should pick up parser preset and fail accordingly', async t => {
 	const cwd = await git.bootstrap('fixtures/parser-preset');
 	const actual = await cli(['--parser-preset', './parser-preset'], {cwd})(
@@ -178,7 +202,7 @@ test('should pick up config from inside git repo with precedence and fail accord
 
 test('should handle --amend with signoff', async () => {
 	const cwd = await git.bootstrap('fixtures/signoff');
-	await writePkg({scripts: {commitmsg: `${bin} -e`}}, {cwd});
+	await writePkg({scripts: {commitmsg: `'${bin}' -e`}}, {cwd});
 
 	await execa('npm', ['install'], {cwd});
 	await execa('git', ['add', 'package.json'], {cwd});

README.md

@@ -53,7 +53,7 @@ To lint commits before they are created you can use the 'commitmsg' hook as desc
 ```json
 {
   "scripts": {
-    "commitmsg": "commitlint -e $GIT_PARAMS"
+    "commitmsg": "commitlint -E GIT_PARAMS"
   }
 }
 ```
@@ -92,7 +92,7 @@ A number of shared configurations are available to install and use with `commitl
 
 ## API
 
-* Alternative, programatic way to interact with `commitlint`
+* Alternative, programmatic way to interact with `commitlint`
 * Packages: 
   * [format](./@commitlint/format) - Format commitlint reports
   * [lint](./@commitlint/lint) - Lint a string against commitlint rules
@@ -111,7 +111,7 @@ A number of shared configurations are available to install and use with `commitl
 
 `commitlint` is considered stable and is used in various projects as development tool. 
 
-We indentify **ease of adoption** and **developer experience** as fields where there
+We identify **ease of adoption** and **developer experience** as fields where there
 is room and need for improvement. The items on the roadmap should enhance `commitlint` regarding those aspects.
 
 * [x] **Adoption**: Provide reusable Travis CI integration: `@commitlint/travis-cli` (https://github.com/marionebl/commitlint/releases/tag/v5.1.0)

docs/guides-local-setup.md

@@ -33,16 +33,16 @@ This allows us to add [git hooks](https://github.com/typicode/husky/blob/master/
 ```json
 {
   "scripts": {
-    "commitmsg": "commitlint -e $GIT_PARAMS"
+    "commitmsg": "commitlint -E GIT_PARAMS"
   }
 }
 ```
 
-Using `commitmsg` gives us exactly what we want: It is executed everytime a new commit is created. Passing husky's `$GIT_PARAMS` to `commitlint` via the `-e|--edit` flag directs it to the relevant edit file. `-e` defaults to `.git/COMMIT_EDITMSG`.
+Using `commitmsg` gives us exactly what we want: It is executed whenever a new commit is created. Passing husky's `GIT_PARAMS` to `commitlint` via the `-E|--env` flag directs it to the relevant edit file. `-e` would default to `.git/COMMIT_EDITMSG`.
 
 ## Test
 
-You can test the hook by simple commiting. You should see something like this if everything works.
+You can test the hook by simply committing. You should see something like this if everything works.
 
 ```bash
 git commit -m "foo: this will fail"

docs/guides-upgrade.md

@@ -20,7 +20,7 @@ npm install --save-dev @commitlint/cli @commitlint/config-conventional
 ```
 {
   "scripts": {
-    "commitmsg": "commitlint -x @commitlint/config-conventional -e $GIT_PARAMS"
+    "commitmsg": "commitlint -x @commitlint/config-conventional -E GIT_PARAMS"
   }
 }
 ```
@@ -47,7 +47,7 @@ npm install --save-dev @commitlint/cli @commitint/config-conventional
 ```
 {
   "scripts": {
-    "commitmsg": "commitlint -e $GIT_PARAMS"
+    "commitmsg": "commitlint -E GIT_PARAMS"
   }
 }
 ```

docs/reference-cli.md

@@ -3,16 +3,19 @@
 ```bash
 ❯ npx commitlint --help
 
-commitlint@4.2.0 - Lint your commit messages
+@commitlint@6.2.0 - Lint your commit messages
 
-  [input] reads from stdin if --edit, --from and --to are omitted
-  --color, -c            toggle colored output, defaults to: true
-  --cwd, -d              directory to execute in, defaults to: /Users/marneb/Documents/oss/commitlint
-  --edit, -e             read last commit message from the specified file or fallbacks to ./.git/COMMIT_EDITMSG
-  --extends, -x          array of shareable configurations to extend
-  --config, -g           path to a custom configuration
-  --from, -f             lower end of the commit range to lint; applies if edit=false
-  --to, -t               upper end of the commit range to lint; applies if edit=false
-  --quiet, -q            toggle console output
-  --parser-preset, -p    configuration preset to use for conventional-commits-parser
+[input] reads from stdin if --edit, --env, --from and --to are omitted
+--color, -c            toggle colored output, defaults to: true
+--config, -g           path to the config file
+--cwd, -d              directory to execute in, defaults to: $CD
+--edit, -e             read last commit message from the specified file or fallbacks to ./.git/COMMIT_EDITMSG
+--env, -E              check message in the file at path given by environment variable value
+--extends, -x          array of shareable configurations to extend
+--help, -h             display this help message
+--from, -f             lower end of the commit range to lint; applies if edit=false
+--parser-preset, -p    configuration preset to use for conventional-commits-parser
+--quiet, -q            toggle console output
+--to, -t               upper end of the commit range to lint; applies if edit=false
+--version, -v          display version information
 ```

package.json

@@ -8,7 +8,7 @@
     "build": "lerna run build --stream --parallel --include-filtered-dependencies",
     "clean": "npx lerna clean --yes && npx lerna run clean --stream --parallel --include-filtered-dependencies",
     "commit": "node @commitlint/prompt-cli/cli.js",
-    "commitmsg": "node @commitlint/cli/lib/cli.js -e $GIT_PARAMS",
+    "commitmsg": "node @commitlint/cli/lib/cli.js -E GIT_PARAMS",
     "deps": "lerna run deps",
     "pkg": "lerna run pkg",
     "docs": "docsify serve docs",