Merge pull request #2079 from Automattic/update/docs-pt-vip-search-re…

…place

 Update the `search-replace` command to follow the VIP-CLI style guide

src/bin/vip-import-sql.js

@@ -400,11 +400,11 @@ void command( {
 	)
 	.option(
 		'in-place',
-		'Perform a search and replace operation on a local SQL file, save the results to the file, then import the updated file.'
+		'Overwrite the local input file with the results of the search and replace operation prior to import.'
 	)
 	.option(
 		'output',
-		'Create a local copy of the imported file with the completed search and replace operations. Ignored if the command includes --in-place, or excludes a --search-replace operation. Accepts a local file path.'
+		'The local file path to save a copy of the results from the search and replace operation when the --search-replace option is passed. Ignored when used with the --in-place option.'
 	)
 	.examples( examples )
 	.argv( process.argv, async ( arg, opts ) => {

src/bin/vip-search-replace.js

@@ -12,33 +12,39 @@ const debug = debugLib( '@automattic/vip:bin:vip-search-replace' );
 const examples = [
 	// `search-replace` flag
 	{
-		usage: 'vip search-replace <file.sql> --search-replace="from,to"',
+		usage: 'vip search-replace file.sql --search-replace="from,to"',
 		description:
-			'Replace instances of <from> with <to> in the provided <file.sql>\n' +
-			'       * Ensure there are no spaces between your search-replace parameters',
+			'Search for every instance of the value "from" in the local input file named "file.sql" and replace it with the value "to".\n' +
+			'       * Results of the operation output to STDOUT by default.',
 	},
 	// `in-place` flag
 	{
-		usage: 'vip search-replace <file.sql> --search-replace="from,to" --in-place',
-		description: 'Perform Search and Replace explicitly on the provided input <file.sql> file',
+		usage: 'vip search-replace file.sql --search-replace="from,to" --in-place',
+		description:
+			'Perform the search and replace operation on the local input file "file.sql" and overwrite the file with the results.',
 	},
 	// `output` flag
 	{
-		usage: 'vip search-replace <file.sql> --search-replace="from,to" --output="<output.sql>"',
+		usage: 'vip search-replace file.sql --search-replace="from,to" --output=output-file.sql',
 		description:
-			'Search and Replace to the specified output <output.sql> file\n' +
-			'       * Has no effect when the `in-place` flag is used',
+			'Perform the search and replace operation and save the results to a local clone of the input file named "output-file.sql".',
 	},
 ];
 
 command( {
 	requiredArgs: 1,
 } )
-	.option( 'search-replace', 'Specify the <from> and <to> pairs to be replaced' )
-	.option( 'in-place', 'Perform the search and replace explicitly on the input file' )
+	.option(
+		'search-replace',
+		'A comma-separated pair of strings that specify the values to search for and replace (e.g. --search-replace="from,to").'
+	)
+	.option(
+		'in-place',
+		'Overwrite the local input file with the results of the search and replace operation.'
+	)
 	.option(
 		'output',
-		'Create a local copy of the file with the completed search and replace operations. Ignored if the command includes --in-place. Accepts a local file path. Defaults to STDOUT.'
+		'The local file path used to save a copy of the results from the search and replace operation. Ignored when used with the --in-place option.'
 	)
 	.examples( examples )
 	.argv( process.argv, async ( arg, opt ) => {

src/bin/vip.js

@@ -37,7 +37,10 @@ const runCmd = async function () {
 		.command( 'export', 'Export a copy of data associated with an environment.' )
 		.command( 'import', 'Import media or SQL database files to an environment.' )
 		.command( 'logs', 'Get logs from your VIP applications' )
-		.command( 'search-replace', 'Perform search and replace tasks on files' )
+		.command(
+			'search-replace',
+			'Search for a string in a local SQL file and replace it with a new string.'
+		)
 		.command( 'slowlogs', 'Retrieve MySQL slow query logs from an environment.' )
 		.command( 'db', "Access an environment's database." )
 		.command( 'sync', 'Sync the database from production to a non-production environment.' )