CLI-1342: [push:artifact] improve docs

src/Command/Push/PushArtifactCommand.php

@@ -57,7 +57,8 @@ protected function configure(): void
             ->acceptEnvironmentId()
             ->setHelp('This command builds a sanitized deploy artifact by running <options=bold>composer install</>, removing sensitive files, and committing vendor directories.' . PHP_EOL . PHP_EOL
                 . 'Vendor directories and scaffold files are committed to the build artifact even if they are ignored in the source repository.' . PHP_EOL . PHP_EOL
-                . 'To run additional build or sanitization steps (e.g. <options=bold>npm install</>), add a <options=bold>post-install-cmd</> script to your <options=bold>composer.json</> file: https://getcomposer.org/doc/articles/scripts.md#command-events')
+                . 'To run additional build or sanitization steps (e.g. <options=bold>npm install</>), add a <options=bold>post-install-cmd</> script to your <options=bold>composer.json</> file: https://getcomposer.org/doc/articles/scripts.md#command-events' . PHP_EOL . PHP_EOL
+                . 'This command is designed for a specific scenario in which there are two branches or repositories involved: a source branch without vendor files committed, and an artifact branch with them. If both your source and destination branches are the same, you should simply use git push instead.')
             ->addUsage('--destination-git-branch=main-build')
             ->addUsage('--source-git-tag=foo-build --destination-git-tag=1.0.0')
             ->addUsage('[email protected]:example.git [email protected]:example.git --destination-git-branch=main-build');

tests/phpunit/src/Commands/Push/PushArtifactCommandTest.php

@@ -24,9 +24,19 @@ protected function createCommand(): CommandBase
         return $this->injectCommand(PushArtifactCommand::class);
     }
 
-    public function testNoAuthenticationRequired(): void
+    public function testPushArtifactHelp(): void
     {
         $help = $this->command->getHelp();
+        $expectedHelp = <<<EOF
+This command builds a sanitized deploy artifact by running <options=bold>composer install</>, removing sensitive files, and committing vendor directories.
+
+Vendor directories and scaffold files are committed to the build artifact even if they are ignored in the source repository.
+
+To run additional build or sanitization steps (e.g. <options=bold>npm install</>), add a <options=bold>post-install-cmd</> script to your <options=bold>composer.json</> file: https://getcomposer.org/doc/articles/scripts.md#command-events
+
+This command is designed for a specific scenario in which there are two branches or repositories involved: a source branch without vendor files committed, and an artifact branch with them. If both your source and destination branches are the same, you should simply use git push instead.
+EOF;
+        self::assertStringContainsStringIgnoringLineEndings($expectedHelp, $help);
         $this->assertStringNotContainsString('This command requires authentication', $help);
     }