[Readme] update usage in README; use md-magic to keep help output in …

…sync

.github/workflows/readme.yml

@@ -0,0 +1,15 @@
+name: 'Tests: readme'
+
+on: [pull_request, push]
+
+jobs:
+  readme:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ljharb/actions/node/install@main
+        name: 'nvm install lts/* && npm install'
+        with:
+          node-version: 'lts/*'
+      - run: npm run generate-readme:check

README.md

@@ -33,21 +33,29 @@ npm install -g can-merge
 
 ## Usage
 
+<!-- MD-MAGIC-EXAMPLE:START (CLI_REFERENCE) -->
 ```txt
 $ npx can-merge --help
-Usage: npx can-merge -p <pr> [-r <repo>]
+Usage: can-merge -p <pr> [-r <repo>]
 
 Options:
-      --help        Show help                                          [boolean]
       --version     Show version number                                [boolean]
-  -p, --pr          pull request                             [string] [required]
+      --help        Show help                                          [boolean]
+  -c, --commit      check commit status               [boolean] [default: false]
+  -p, --pr          pull request                                        [string]
+      --remote      remote name                     [string] [default: "origin"]
   -r, --repo        repository            [string] [default: "ljharb/can-merge"]
-  -s, --sha      commit SHA                           [string] [default: "HEAD"]
-  -t, --token       github access token                      [string] [required]
+      --retryDelay  delay before polling the api        [number] [default: 5000]
+  -s, --sha         commit SHA                        [string] [default: "HEAD"]
+      --token       github access token                      [string] [required]
+  -w, --watch       watch pending checks                               [boolean]
+
 ```
+<!-- MD-MAGIC-EXAMPLE:END -->
 
 **NOTE**:
-- Export your GitHub Personal Access Token and set it as `$GITHUB_TOKEN`, or pass it with the `-t` option.
+
+- Export your GitHub Personal Access Token and set it as `$GH_TOKEN` or `$GITHUB_TOKEN`, or pass it with the `-t` option.
 
 The `can-merge` tool will exit with a non-zero exit code if the pull request is not mergeable or blocked. It will exit with the exit code 0 if the pull request can be merged. You can use this tool with other scripts and tool to perform actions based on the exit code of this tool.
 
@@ -59,14 +67,18 @@ For example, you can use the `can-merge` tool to check if a pull request can be
 
 Shows the usage information as in [Usage](#usage) section.
 
-### `--version`
+### `-c, --commit`
 
-Shows the semantic version number of the tool.
+Used to check the commit status.
 
 ### `-p, --pr`
 
 Used to specify the Pull Request number being used on [GitHub](https://github.com).
 
+### `--remote`
+
+Used to specify the remote to check.
+
 ### `-r, --repo`
 
 Used to specify the repository if there is no GitHub remote configured or if it is different from the repository you are currently in.
@@ -75,21 +87,17 @@ Used to specify the repository if there is no GitHub remote configured or if it
 
 Specify the [commit-ish](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefcommit-ishacommit-ishalsocommittish) to be used. Defaults to the current SHA.
 
-<!--
 ### `--retryDelay`
 
- Used to specify the delay before polling the GitHub API for checking if the state of status checks have changed. To be used along with the `-w, --watch` option.
--->
+Used to specify the delay before polling the GitHub API for checking if the state of status checks have changed. To be used along with the `-w, --watch` option.
 
 ### `-t, --token`
 
 Used to specify the GitHub Personal Access Token needed to authenticate queries to the GitHub API.
 
-<!--
 ### `-w, --watch`
 
 Used to specify if the tool should keep polling for changes in the status checks untill all of them have completed.
--->
 
 ## License
 

markdown.config.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const childProcess = require('child_process');
+
+module.exports = {
+	matchWord: 'MD-MAGIC-EXAMPLE',
+	transforms: {
+		/* Match <!-- MD-MAGIC-EXAMPLE:START (CLI_REFERENCE) --> */
+		CLI_REFERENCE() {
+			const result = childProcess.execSync('node ./bin/can-merge --help', {
+				env: { ...process.env, GH_TOKEN: undefined, GITHUB_TOKEN: undefined },
+			});
+			return [].concat('```txt', '$ npx can-merge --help', String(result), '```').join('\n');
+		},
+	},
+	callback() {
+		console.log('markdown processing done');
+	},
+};
+

package.json

@@ -13,7 +13,9 @@
 		"pretest": "npm run lint",
 		"tests-only": "nyc tape 'test/**/*.js'| tap-spec",
 		"test": "npm run tests-only",
-		"posttest": "aud --production"
+		"posttest": "aud --production",
+		"generate-readme": "md-magic --path README.md --ignore 'node_modules'",
+		"generate-readme:check": "npm run generate-readme && git diff --exit-code README.md"
 	},
 	"repository": {
 		"type": "git",
@@ -31,6 +33,7 @@
 		"aud": "^2.0.0",
 		"eslint": "=8.8.0",
 		"in-publish": "^2.0.1",
+		"markdown-magic": "^2.5.2",
 		"nyc": "^15.1.0",
 		"object.fromentries": "^2.0.5",
 		"safe-publish-latest": "^2.0.0",