Add base option for path resolution

sindresorhus · sindresorhus · commit 28175cbd7f09 · 2026-02-02T11:46:01.000+07:00
Fixes #113
diff --git a/glob-pattern.js b/glob-pattern.js
@@ -36,7 +36,10 @@ export default class GlobPattern {
 	}
 
 	get normalizedPath() {
-		const segments = this.originalPath.split('/');
+		const normalizedPattern = this.path.startsWith('!') && !this.path.startsWith('!(')
+			? this.path.slice(1)
+			: this.path;
+		const segments = normalizedPattern.split('/');
 		const magicIndex = segments.findIndex(item => item ? isDynamicPattern(item) : false);
 		const normalized = segments.slice(0, magicIndex).join('/');
 
diff --git a/index.d.ts b/index.d.ts
@@ -91,6 +91,13 @@ export type Options = {
 	*/
 	readonly cwd?: string;
 
+	/**
+	Choose how destination paths are calculated for patterns. By default, globs are resolved relative to their parent and explicit paths are resolved relative to `cwd`. Set to `'pattern'` to make explicit paths behave like globs, or `'cwd'` to make globs behave like explicit paths.
+
+	@default undefined
+	*/
+	readonly base?: 'cwd' | 'pattern';
+
 	/**
 	Flatten directory tree.
 
diff --git a/index.js b/index.js
@@ -246,6 +246,33 @@ const relativizeWithin = (base, file) => {
 	return relativePath;
 };
 
+const resolveRelativePath = (bases, file) => {
+	for (const base of bases) {
+		const relativePath = relativizeWithin(base, file);
+		if (relativePath !== undefined) {
+			return relativePath;
+		}
+	}
+
+	return path.basename(file);
+};
+
+const resolveCwdRelativePathForGlob = (entry, options) => {
+	const relativeToCwd = relativizeWithin(options.cwd, entry.path);
+	if (relativeToCwd !== undefined) {
+		return relativeToCwd;
+	}
+
+	const globParent = entry.pattern.normalizedPath;
+	const relativeToGlobParent = relativizeWithin(globParent, entry.path);
+	if (relativeToGlobParent !== undefined) {
+		const globParentBasename = path.basename(globParent);
+		return globParentBasename === '' ? relativeToGlobParent : path.join(globParentBasename, relativeToGlobParent);
+	}
+
+	return path.basename(entry.path);
+};
+
 const computeToForGlob = ({entry, destination, options}) => {
 	if (options.flat) {
 		return path.isAbsolute(destination)
@@ -256,9 +283,11 @@ const computeToForGlob = ({entry, destination, options}) => {
 	// Prefer glob-parent behavior to match existing semantics,
 	// but defend against self-copy / traversal (#114).
 	const from = path.resolve(entry.path);
-	const baseA = entry.pattern.normalizedPath; // Glob parent inside cwd
+	const baseA = entry.pattern.normalizedPath; // Glob parent path
 	const baseB = options.cwd;
-	const relativePath = relativizeWithin(baseA, entry.path) ?? relativizeWithin(baseB, entry.path) ?? path.basename(entry.path);
+	const relativePath = options.base === 'cwd'
+		? resolveCwdRelativePathForGlob(entry, options)
+		: resolveRelativePath([baseA, baseB], entry.path);
 	let toPath = path.join(destination, relativePath);
 
 	// Guard: never copy a file into itself (can truncate under concurrency).
@@ -281,9 +310,18 @@ const computeToForNonGlob = ({entry, destination, options}) => {
 		? destination
 		: path.join(options.cwd, destination);
 
-	const insideCwd = !path.relative(options.cwd, entry.path).startsWith('..');
+	if (options.base === 'pattern') {
+		const patternBase = entry.pattern.isDirectory
+			? path.resolve(options.cwd, entry.pattern.originalPath)
+			: path.resolve(options.cwd, path.dirname(entry.pattern.originalPath));
+		const relativePath = resolveRelativePath([patternBase], entry.path);
+		return path.join(baseDestination, relativePath);
+	}
 
-	// TODO: This check will not work correctly if `options.cwd` and `entry.path` are on different partitions on Windows, see: https://github.com/sindresorhus/import-local/pull/12
+	const relativeToCwd = relativizeWithin(options.cwd, entry.path);
+	const insideCwd = relativeToCwd !== undefined;
+
+	// This check should treat different partitions on Windows as outside the cwd.
 	if (entry.pattern.isDirectory && !insideCwd) {
 		const originalDir = path.resolve(options.cwd, entry.pattern.originalPath);
 		return path.join(baseDestination, path.basename(originalDir), path.relative(originalDir, entry.path));
@@ -301,7 +339,11 @@ const computeToForNonGlob = ({entry, destination, options}) => {
 		return path.join(baseDestination, entry.name);
 	}
 
-	return path.join(baseDestination, path.relative(options.cwd, entry.path));
+	if (relativeToCwd === undefined) {
+		return path.join(baseDestination, entry.name);
+	}
+
+	return path.join(baseDestination, relativeToCwd);
 };
 
 const preprocessDestinationPath = ({entry, destination, options}) => (
@@ -407,6 +449,10 @@ export default function cpy(
 	const promise = (async () => {
 		options.signal?.throwIfAborted();
 
+		if (options.base !== undefined && options.base !== 'cwd' && options.base !== 'pattern') {
+			throw new TypeError('`base` must be "cwd" or "pattern"');
+		}
+
 		/**
 		@type {Entry[]}
 		*/
diff --git a/index.test-d.ts b/index.test-d.ts
@@ -18,6 +18,8 @@ expectType<Promise<string[]> & ProgressEmitter>(cpy('foo.js', 'destination', {
 	},
 }));
 expectType<Promise<string[]> & ProgressEmitter>(cpy('foo.js', 'destination', {cwd: '/'}));
+expectType<Promise<string[]> & ProgressEmitter>(cpy('foo.js', 'destination', {base: 'pattern'}));
+expectType<Promise<string[]> & ProgressEmitter>(cpy('foo.js', 'destination', {base: 'cwd'}));
 expectType<Promise<string[]> & ProgressEmitter>(cpy('foo.js', 'destination', {flat: true}));
 expectType<Promise<string[]> & ProgressEmitter>(cpy('foo.js', 'destination', {overwrite: false}));
 expectType<Promise<string[]> & ProgressEmitter>(cpy('foo.js', 'destination', {concurrency: 2}));
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "cpy",
-	"version": "12.1.0",
+	"version": "12.2.0",
 	"description": "Copy files",
 	"license": "MIT",
 	"repository": "sindresorhus/cpy",
diff --git a/readme.md b/readme.md
@@ -78,12 +78,6 @@ Default: `process.cwd()`
 
 Working directory to find source files.
 
-> [!NOTE]
-> Globs and explicit paths preserve paths differently.
-> Globs keep paths **relative to the glob’s parent** (`source/*.md` → `distribution/readme.md`).
-> Explicit paths keep paths **relative to `cwd`** (`source/file.js` → `distribution/source/file.js`).
-> Use a single glob or set `cwd` so all patterns share the same base.
-
 ##### overwrite
 
 Type: `boolean`\
@@ -106,6 +100,13 @@ await cpy('src/**/*.js', 'destination', {
 });
 ```
 
+##### base
+
+Type: `'cwd' | 'pattern'`\
+Default: `undefined`
+
+Choose how destination paths are calculated for patterns. By default, globs are resolved relative to their parent and explicit paths are resolved relative to `cwd`. Set to `'pattern'` to make explicit paths behave like globs, or `'cwd'` to make globs behave like explicit paths.
+
 ##### rename
 
 Type: `string | Function`
diff --git a/test.js b/test.js
@@ -79,6 +79,13 @@ test('throws on invalid concurrency value', async () => {
 	await assert.rejects(cpy(['license', 'package.json'], context.tmp, {concurrency: 'foo'}));
 });
 
+test('throws on invalid base option', async () => {
+	await assert.rejects(
+		cpy(['license'], context.tmp, {base: 'invalid'}),
+		expectError(TypeError, /`base` must be/),
+	);
+});
+
 test('copy array of files with filter', async () => {
 	await cpy(['license', 'package.json'], context.tmp, {
 		filter(file) {
@@ -238,6 +245,219 @@ test('path structure', async () => {
 	);
 });
 
+test('base option: pattern aligns explicit paths with globs', async () => {
+	fs.mkdirSync(path.join(context.tmp, 'src'), {recursive: true});
+	fs.writeFileSync(path.join(context.tmp, 'src/hello-world.js'), 'console.log("hello");');
+	fs.writeFileSync(path.join(context.tmp, 'src/README.md'), 'readme');
+
+	await cpy(['src/*.md', 'src/hello-world.js'], 'dist', {
+		cwd: context.tmp,
+		base: 'pattern',
+	});
+
+	assert.strictEqual(
+		read(context.tmp, 'src/README.md'),
+		read(context.tmp, 'dist/README.md'),
+	);
+	assert.strictEqual(
+		read(context.tmp, 'src/hello-world.js'),
+		read(context.tmp, 'dist/hello-world.js'),
+	);
+});
+
+test('base option: cwd preserves nested glob structure from cwd', async () => {
+	writeFiles(context.tmp, {
+		'resources/views/app.edge': 'app',
+		'resources/views/nested/baz.edge': 'baz',
+	});
+
+	const buildDirectory = path.join(context.tmp, 'build');
+
+	await cpy(['resources/views/**/*.edge'], buildDirectory, {
+		cwd: context.tmp,
+		base: 'cwd',
+	});
+
+	assert.strictEqual(
+		read(context.tmp, 'resources', 'views', 'app.edge'),
+		read(buildDirectory, 'resources', 'views', 'app.edge'),
+	);
+	assert.strictEqual(
+		read(context.tmp, 'resources', 'views', 'nested', 'baz.edge'),
+		read(buildDirectory, 'resources', 'views', 'nested', 'baz.edge'),
+	);
+});
+
+test('base option: cwd aligns globs outside cwd with explicit paths', async () => {
+	const root = context.dir;
+	const cwd = path.join(root, 'cwd');
+	const src = path.join(root, 'src');
+	const out = path.join(cwd, 'out');
+	fs.mkdirSync(cwd, {recursive: true});
+	fs.mkdirSync(src, {recursive: true});
+	writeFiles(root, {
+		'src/root.js': 'root',
+		'src/nested/inner.js': 'inner',
+		'src/nested/README.md': 'readme',
+	});
+
+	await cpy(['../src/**/*.js'], 'out', {
+		cwd,
+		base: 'cwd',
+	});
+
+	assert.strictEqual(read(src, 'root.js'), read(out, 'src/root.js'));
+	assert.strictEqual(read(src, 'nested/inner.js'), read(out, 'src/nested/inner.js'));
+	assert.ok(!fs.existsSync(path.join(out, 'src/nested/README.md')));
+});
+
+test('base option: cwd aligns absolute globs outside cwd', async () => {
+	const root = context.dir;
+	const cwd = path.join(root, 'cwd');
+	const src = path.join(root, 'src');
+	const out = path.join(cwd, 'out');
+	fs.mkdirSync(cwd, {recursive: true});
+	fs.mkdirSync(path.join(src, 'nested'), {recursive: true});
+	fs.writeFileSync(path.join(src, 'nested/inner.js'), 'inner');
+
+	const pattern = path.join(src, '**/*.js');
+	await cpy([pattern], 'out', {
+		cwd,
+		base: 'cwd',
+	});
+
+	assert.strictEqual(read(src, 'nested/inner.js'), read(out, 'src/nested/inner.js'));
+});
+
+test('base option: cwd aligns outside globs with absolute destination', async () => {
+	const root = context.dir;
+	const cwd = path.join(root, 'cwd');
+	const src = path.join(root, 'src');
+	const out = path.join(root, 'out');
+	fs.mkdirSync(cwd, {recursive: true});
+	fs.mkdirSync(path.join(src, 'nested'), {recursive: true});
+	fs.writeFileSync(path.join(src, 'nested/inner.js'), 'inner');
+
+	await cpy(['../src/**/*.js'], out, {
+		cwd,
+		base: 'cwd',
+	});
+
+	assert.strictEqual(read(src, 'nested/inner.js'), read(out, 'src/nested/inner.js'));
+});
+
+test('base option: cwd aligns outside globs with symlinked parent', async () => {
+	const root = context.dir;
+	const cwd = path.join(root, 'cwd');
+	const src = path.join(root, 'src');
+	const alias = path.join(root, 'alias');
+	const out = path.join(cwd, 'out');
+	fs.mkdirSync(cwd, {recursive: true});
+	fs.mkdirSync(path.join(src, 'nested'), {recursive: true});
+	fs.writeFileSync(path.join(src, 'nested/inner.js'), 'inner');
+	fs.symlinkSync(src, alias, 'dir');
+
+	await cpy(['../alias/**/*.js'], 'out', {
+		cwd,
+		base: 'cwd',
+	});
+
+	assert.strictEqual(read(src, 'nested/inner.js'), read(out, 'alias/nested/inner.js'));
+});
+
+test('base option: cwd does not escape destination for dynamic absolute globs', {skip: process.platform === 'win32'}, async () => {
+	const root = context.dir;
+	const cwd = path.join(root, 'nested', 'cwd');
+	const source = path.join(root, 'source');
+	const out = path.join(root, 'dest', 'nested');
+	fs.mkdirSync(cwd, {recursive: true});
+	fs.mkdirSync(path.join(source, 'nested'), {recursive: true});
+	fs.writeFileSync(path.join(source, 'nested', 'file.js'), 'content');
+
+	const rootSegments = root.split(path.sep).filter(Boolean);
+	if (rootSegments.length < 2) {
+		return;
+	}
+
+	const pattern = path.posix.join('/', '*', ...rootSegments.slice(1), 'source', '**/*.js');
+	await cpy([pattern], out, {
+		cwd,
+		base: 'cwd',
+	});
+
+	assert.strictEqual(read(source, 'nested/file.js'), read(out, 'file.js'));
+	assert.ok(!fs.existsSync(path.join(root, 'dest', 'source', 'nested', 'file.js')));
+});
+
+test('base option: cwd aligns parent directory globs outside cwd', async () => {
+	const root = context.dir;
+	const cwd = path.join(root, 'cwd');
+	const out = path.join(cwd, 'out');
+	fs.mkdirSync(cwd, {recursive: true});
+	writeFiles(root, {
+		'root.js': 'root',
+		'nested/inner.js': 'inner',
+	});
+
+	await cpy(['../**/*.js'], 'out', {
+		cwd,
+		base: 'cwd',
+	});
+
+	const rootName = path.basename(root);
+	assert.strictEqual(read(root, 'root.js'), read(out, rootName, 'root.js'));
+	assert.strictEqual(read(root, 'nested/inner.js'), read(out, rootName, 'nested/inner.js'));
+});
+
+test('base option: cwd keeps distinct outside glob parents', async () => {
+	const root = context.dir;
+	const cwd = path.join(root, 'cwd');
+	const first = path.join(root, 'first');
+	const second = path.join(root, 'second');
+	const out = path.join(cwd, 'out');
+	fs.mkdirSync(cwd, {recursive: true});
+	fs.mkdirSync(first, {recursive: true});
+	fs.mkdirSync(second, {recursive: true});
+	writeFiles(root, {
+		'first/index.js': 'first',
+		'first/nested/shared.js': 'shared-1',
+		'second/index.js': 'second',
+		'second/nested/shared.js': 'shared-2',
+	});
+
+	await cpy(['../first/**/*.js', '../second/**/*.js'], 'out', {
+		cwd,
+		base: 'cwd',
+	});
+
+	assert.strictEqual(read(first, 'index.js'), read(out, 'first/index.js'));
+	assert.strictEqual(read(first, 'nested/shared.js'), read(out, 'first/nested/shared.js'));
+	assert.strictEqual(read(second, 'index.js'), read(out, 'second/index.js'));
+	assert.strictEqual(read(second, 'nested/shared.js'), read(out, 'second/nested/shared.js'));
+});
+
+test('base option: pattern with directory source copies contents without top-level directory', async () => {
+	writeFiles(context.tmp, {
+		'source/file.txt': 'content',
+		'source/nested/inner.txt': 'inner',
+	});
+
+	await cpy(['source'], 'destination', {
+		cwd: context.tmp,
+		base: 'pattern',
+	});
+
+	assert.strictEqual(
+		read(context.tmp, 'source/file.txt'),
+		read(context.tmp, 'destination/file.txt'),
+	);
+	assert.strictEqual(
+		read(context.tmp, 'source/nested/inner.txt'),
+		read(context.tmp, 'destination/nested/inner.txt'),
+	);
+	assert.ok(!fs.existsSync(path.join(context.tmp, 'destination/source')));
+});
+
 test('directory source outside cwd preserves structure under destination', async () => {
 	const root = temporaryDirectory();
 	const cwd = path.join(root, 'cwd');

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "cpy",`
`3`		`- "version": "12.1.0",`
	`3`	`+ "version": "12.2.0",`
`4`	`4`	`"description": "Copy files",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"repository": "sindresorhus/cpy",`