From 5d039c2dcd9a93fd8d67ad570b409545af16ad74 Mon Sep 17 00:00:00 2001 From: Isaac Mann Date: Tue, 10 Sep 2024 12:36:32 -0400 Subject: [PATCH] docs(core): reword import help text (#27732) Updates the help text for the `nx import` command --- .../src/command-line/import/command-object.ts | 10 +-- packages/nx/src/command-line/import/import.ts | 69 ++++++++++--------- 2 files changed, 43 insertions(+), 36 deletions(-) diff --git a/packages/nx/src/command-line/import/command-object.ts b/packages/nx/src/command-line/import/command-object.ts index ea584b53b5245..6a7310c377e5f 100644 --- a/packages/nx/src/command-line/import/command-object.ts +++ b/packages/nx/src/command-line/import/command-object.ts @@ -4,23 +4,25 @@ import { withVerbose } from '../yargs-utils/shared-options'; import { handleErrors } from '../../utils/params'; export const yargsImportCommand: CommandModule = { - command: 'import [sourceRemoteUrl] [destination]', + command: 'import [sourceRepository] [destinationDirectory]', describe: false, builder: (yargs) => linkToNxDevAndExamples( withVerbose( yargs - .positional('sourceRemoteUrl', { + .positional('sourceRepository', { type: 'string', description: 'The remote URL of the source to import.', }) - .positional('destination', { + .positional('destinationDirectory', { type: 'string', + alias: 'destination', description: 'The directory in the current workspace to import into.', }) - .option('source', { + .option('sourceDirectory', { type: 'string', + alias: 'source', description: 'The directory in the source repository to import from.', }) diff --git a/packages/nx/src/command-line/import/import.ts b/packages/nx/src/command-line/import/import.ts index 3d425c1226424..21d91e4cc7bd6 100644 --- a/packages/nx/src/command-line/import/import.ts +++ b/packages/nx/src/command-line/import/import.ts @@ -36,7 +36,7 @@ export interface ImportOptions { /** * The remote URL of the repository to import */ - sourceRemoteUrl: string; + sourceRepository: string; /** * The branch or reference to import */ @@ -59,50 +59,49 @@ export interface ImportOptions { } export async function importHandler(options: ImportOptions) { - let { sourceRemoteUrl, ref, source, destination } = options; + let { sourceRepository, ref, source, destination } = options; output.log({ title: - 'Nx will walk you through the process of importing code from another repository into this workspace:', + 'Nx will walk you through the process of importing code from the source repository into this repository:', bodyLines: [ - `1. Nx will clone the other repository into a temporary directory`, - `2. Code to be imported will be moved to the same directory it will be imported into on a temporary branch`, - `3. The code will be merged into the current branch in this workspace`, - `4. Nx will recommend plugins to integrate tools used in the imported code with Nx`, - `5. The code will be successfully imported into this workspace`, + `1. Nx will clone the source repository into a temporary directory`, + `2. The project code from the sourceDirectory will be moved to the destinationDirectory on a temporary branch in this repository`, + `3. The temporary branch will be merged into the current branch in this repository`, + `4. Nx will recommend plugins to integrate any new tools used in the imported code`, '', - `Git history will be preserved during this process`, + `Git history will be preserved during this process as long as you MERGE these changes. Do NOT squash and do NOT rebase the changes when merging branches. If you would like to UNDO these changes, run "git reset HEAD~1 --hard"`, ], }); const tempImportDirectory = join(tmpdir, 'nx-import'); - if (!sourceRemoteUrl) { - sourceRemoteUrl = ( - await prompt<{ sourceRemoteUrl: string }>([ + if (!sourceRepository) { + sourceRepository = ( + await prompt<{ sourceRepository: string }>([ { type: 'input', - name: 'sourceRemoteUrl', + name: 'sourceRepository', message: 'What is the URL of the repository you want to import? (This can be a local git repository or a git remote URL)', required: true, }, ]) - ).sourceRemoteUrl; + ).sourceRepository; } try { - const maybeLocalDirectory = await stat(sourceRemoteUrl); + const maybeLocalDirectory = await stat(sourceRepository); if (maybeLocalDirectory.isDirectory()) { - sourceRemoteUrl = resolve(sourceRemoteUrl); + sourceRepository = resolve(sourceRepository); } } catch (e) { // It's a remote url } - const sourceRepoPath = join(tempImportDirectory, 'repo'); + const sourceTempRepoPath = join(tempImportDirectory, 'repo'); const spinner = createSpinner( - `Cloning ${sourceRemoteUrl} into a temporary directory: ${sourceRepoPath} (Use --depth to limit commit history and speed up clone times)` + `Cloning ${sourceRepository} into a temporary directory: ${sourceTempRepoPath} (Use --depth to limit commit history and speed up clone times)` ).start(); try { await rm(tempImportDirectory, { recursive: true }); @@ -111,17 +110,23 @@ export async function importHandler(options: ImportOptions) { let sourceGitClient: GitRepository; try { - sourceGitClient = await cloneFromUpstream(sourceRemoteUrl, sourceRepoPath, { - originName: importRemoteName, - depth: options.depth, - }); + sourceGitClient = await cloneFromUpstream( + sourceRepository, + sourceTempRepoPath, + { + originName: importRemoteName, + depth: options.depth, + } + ); } catch (e) { - spinner.fail(`Failed to clone ${sourceRemoteUrl} into ${sourceRepoPath}`); - let errorMessage = `Failed to clone ${sourceRemoteUrl} into ${sourceRepoPath}. Please double check the remote and try again.\n${e.message}`; + spinner.fail( + `Failed to clone ${sourceRepository} into ${sourceTempRepoPath}` + ); + let errorMessage = `Failed to clone ${sourceRepository} into ${sourceTempRepoPath}. Please double check the remote and try again.\n${e.message}`; throw new Error(errorMessage); } - spinner.succeed(`Cloned into ${sourceRepoPath}`); + spinner.succeed(`Cloned into ${sourceTempRepoPath}`); // Detecting the package manager before preparing the source repo for import. const sourcePackageManager = detectPackageManager(sourceGitClient.root); @@ -171,7 +176,7 @@ export async function importHandler(options: ImportOptions) { ).destination; } - const absSource = join(sourceRepoPath, source); + const absSource = join(sourceTempRepoPath, source); const absDestination = join(process.cwd(), destination); const destinationGitClient = new GitRepository(process.cwd()); @@ -180,7 +185,7 @@ export async function importHandler(options: ImportOptions) { const tempImportBranch = getTempImportBranch(ref); await sourceGitClient.addFetchRemote(importRemoteName, ref); await sourceGitClient.fetch(importRemoteName, ref); - spinner.succeed(`Fetched ${ref} from ${sourceRemoteUrl}`); + spinner.succeed(`Fetched ${ref} from ${sourceRepository}`); spinner.start( `Checking out a temporary branch, ${tempImportBranch} based on ${ref}` ); @@ -195,7 +200,7 @@ export async function importHandler(options: ImportOptions) { await stat(absSource); } catch (e) { throw new Error( - `The source directory ${source} does not exist in ${sourceRemoteUrl}. Please double check to make sure it exists.` + `The source directory ${source} does not exist in ${sourceRepository}. Please double check to make sure it exists.` ); } @@ -215,18 +220,18 @@ export async function importHandler(options: ImportOptions) { source, relativeDestination, tempImportBranch, - sourceRemoteUrl + sourceRepository ); await createTemporaryRemote( destinationGitClient, - join(sourceRepoPath, '.git'), + join(sourceTempRepoPath, '.git'), importRemoteName ); await mergeRemoteSource( destinationGitClient, - sourceRemoteUrl, + sourceRepository, tempImportBranch, destination, importRemoteName, @@ -311,7 +316,7 @@ export async function importHandler(options: ImportOptions) { output.log({ title: `Check root dependencies`, bodyLines: [ - `"dependencies" and "devDependencies" are not imported from the source repository (${sourceRemoteUrl}).`, + `"dependencies" and "devDependencies" are not imported from the source repository (${sourceRepository}).`, `You may need to add some of those dependencies to this workspace in order to run tasks successfully.`, ], });