From b67b4c8850c9b9d26294fc0222cb1d7422e27833 Mon Sep 17 00:00:00 2001
From: Dane Powell <git@danepowell.com>
Date: Wed, 23 Oct 2024 13:27:06 -0700
Subject: [PATCH] CLI-1342: [push:artifact] improve docs (#1819)

* CLI-1342: [push:artifact] improve docs

* kill mutants

* fix
---
 src/Command/Push/PushArtifactCommand.php             |  3 ++-
 .../src/Commands/Push/PushArtifactCommandTest.php    | 12 +++++++++++-
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/src/Command/Push/PushArtifactCommand.php b/src/Command/Push/PushArtifactCommand.php
index f4c0246c2..389c42b05 100644
--- a/src/Command/Push/PushArtifactCommand.php
+++ b/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('--destination-git-urls=example@svn-1.prod.hosting.acquia.com:example.git --destination-git-urls=example@svn-2.prod.hosting.acquia.com:example.git --destination-git-branch=main-build');
diff --git a/tests/phpunit/src/Commands/Push/PushArtifactCommandTest.php b/tests/phpunit/src/Commands/Push/PushArtifactCommandTest.php
index 6c85126d5..1a4cca06c 100644
--- a/tests/phpunit/src/Commands/Push/PushArtifactCommandTest.php
+++ b/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);
     }