Repository: oclif/core
Pull request #229 (2021-08-09 19:15:46)

feat: support multiple examples commands under a single description
Adds support for multiple example commands under a single description:

```
EXAMPLES
  Deploy all custom objects and Apex classes (both examples are equivalent):

    $ sf deploy metadata --metadata CustomObject ApexClass
    $ sf deploy metadata --metadata CustomObject --metadata ApexClass
```

@W-9719622@


Patch:
diff --git a/src/help/command.ts b/src/help/command.ts
index cf9d71c..68d5d61 100644
--- a/src/help/command.ts
+++ b/src/help/command.ts
@@ -190,21 +190,21 @@ export class CommandHelp extends HelpFormatter {
 
     const body = castArray(examples).map(a => {
       let description
-      let command
+      let commands
       if (typeof a === 'string') {
         const lines = a
         .split(POSSIBLE_LINE_FEED)
         .filter(line => Boolean(line))
         // If the example is <description>\n<command> then format correctly
-        if (lines.length === 2 && !isCommand(lines[0]) && isCommand(lines[1])) {
+        if (lines.length >= 2 && !isCommand(lines[0]) && lines.slice(1).every(isCommand)) {
           description = lines[0]
-          command = lines[1]
+          commands = lines.slice(1)
         } else {
           return lines.map(line => formatIfCommand(line)).join('\n')
         }
       } else {
         description = a.description
-        command = a.command
+        commands = [a.command]
       }
 
       const multilineSeparator =
@@ -214,12 +214,14 @@ export class CommandHelp extends HelpFormatter {
 
       // The command will be indented in the section, which is also indented
       const finalIndentedSpacing = this.indentSpacing * 2
-      // First indent keeping room for escaped newlines
-      const multilineCommand = this.indent(this.wrap(formatIfCommand(command), finalIndentedSpacing + 4))
-      // Then add the escaped newline
-      .split(POSSIBLE_LINE_FEED).join(` ${multilineSeparator}\n  `)
-
-      return `${this.wrap(description, finalIndentedSpacing)}\n\n${multilineCommand}`
+      const multilineCommands = commands.map(c => {
+        // First indent keeping room for escaped newlines
+        return this.indent(this.wrap(formatIfCommand(c), finalIndentedSpacing + 4))
+        // Then add the escaped newline
+        .split(POSSIBLE_LINE_FEED).join(` ${multilineSeparator}\n  `)
+      }).join('\n')
+
+      return `${this.wrap(description, finalIndentedSpacing)}\n\n${multilineCommands}`
     }).join('\n\n')
     return body
   }


Test patch:
diff --git a/test/help/format-command.test.ts b/test/help/format-command.test.ts
index ee93f04..cecff0f 100644
--- a/test/help/format-command.test.ts
+++ b/test/help/format-command.test.ts
@@ -591,6 +591,21 @@ EXAMPLES
 
     $ oclif oclif:command --help`))
 
+    test
+    .commandHelp(class extends Command {
+        static id = 'oclif:command'
+
+        static examples = ['Prints out help.\n<%= config.bin %> <%= command.id %> --help\n<%= config.bin %> <%= command.id %> --help']
+    })
+    .it('formats if multiple command with description', (ctx: any) => expect(ctx.commandHelp).to.equal(`USAGE
+  $ oclif oclif:command
+
+EXAMPLES
+  Prints out help.
+
+    $ oclif oclif:command --help
+    $ oclif oclif:command --help`))
+
     test
     .commandHelp(class extends Command {
         static id = 'oclif:command'