From 91bfa8d8e02f8116a680d01a5e34283766fde8ff Mon Sep 17 00:00:00 2001
From: John Gee <john@ruru.gen.nz>
Date: Mon, 19 Dec 2022 20:06:58 +1300
Subject: [PATCH] Add mention of .alias() to README. (#1833)

---
 Readme.md         |  2 ++
 examples/alias.js | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 examples/alias.js

diff --git a/Readme.md b/Readme.md
index 2e377bcc3..ed19cff63 100644
--- a/Readme.md
+++ b/Readme.md
@@ -543,6 +543,8 @@ Configuration options can be passed with the call to `.command()` and `.addComma
 remove the command from the generated help output. Specifying `isDefault: true` will run the subcommand if no other
 subcommand is specified ([example](./examples/defaultCommand.js)).
 
+You can add alternative names for a command with `.alias()`. ([example](./examples/alias.js))
+
 For safety, `.addCommand()` does not automatically copy the inherited settings from the parent command. There is a helper routine `.copyInheritedSettings()` for copying the settings when they are wanted.
 
 ### Command-arguments
diff --git a/examples/alias.js b/examples/alias.js
new file mode 100644
index 000000000..ca9a9cd6d
--- /dev/null
+++ b/examples/alias.js
@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+// This example shows giving alternative names for a command.
+
+// const { Command } = require('commander'); // (normal include)
+const { Command } = require('../'); // include commander in git clone of commander repo
+const program = new Command();
+
+program
+  .command('exec')
+  .argument('<script>')
+  .alias('ex')
+  .action((script) => {
+    console.log(`execute: ${script}`);
+  });
+
+program
+  .command('print')
+  .argument('<file>')
+  // Multiple aliases is unusual but supported! You can call alias multiple times,
+  // and/or add multiple aliases at once. Only the first alias is displayed in the help.
+  .alias('p')
+  .alias('pr')
+  .aliases(['display', 'show'])
+  .action((file) => {
+    console.log(`print: ${file}`);
+  });
+
+program.parse();
+
+// Try the following:
+//    node alias.js --help
+//    node alias.js exec script
+//    node alias.js ex script
+//    node alias.js print file
+//    node alias.js pr file
+//    node alias.js show file