Add option to mount a worktree's common folder

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Notable changes.
 
+## January 2026
+
+### [0.81.0]
+- Add option to mount a worktree's common folder. (https://github.com/devcontainers/cli/pull/1127)
+
 ## December 2025
 
 ### [0.80.3]

package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@devcontainers/cli",
 	"description": "Dev Containers CLI",
-	"version": "0.80.3",
+	"version": "0.81.0",
 	"bin": {
 		"devcontainer": "devcontainer.js"
 	},

src/spec-node/configContainer.ts

@@ -46,7 +46,7 @@ async function resolveWithLocalFolder(params: DockerResolverParameters, parsedAu
 		? (await getDevContainerConfigPathIn(cliHost, workspace.configFolderPath)
 			|| (overrideConfigFile ? getDefaultDevContainerConfigPath(cliHost, workspace.configFolderPath) : undefined))
 		: overrideConfigFile;
-	const configs = configPath && await readDevContainerConfigFile(cliHost, workspace, configPath, params.mountWorkspaceGitRoot, output, workspaceMountConsistencyDefault, overrideConfigFile) || undefined;
+	const configs = configPath && await readDevContainerConfigFile(cliHost, workspace, configPath, params.mountWorkspaceGitRoot, params.mountGitWorktreeCommonDir, output, workspaceMountConsistencyDefault, overrideConfigFile) || undefined;
 	if (!configs) {
 		if (configPath || workspace) {
 			throw new ContainerError({ description: `Dev container config (${uriToFsPath(configPath || getDefaultDevContainerConfigPath(cliHost, workspace!.configFolderPath), cliHost.platform)}) not found.` });
@@ -79,7 +79,7 @@ async function resolveWithLocalFolder(params: DockerResolverParameters, parsedAu
 	return result;
 }
 
-export async function readDevContainerConfigFile(cliHost: CLIHost, workspace: Workspace | undefined, configFile: URI, mountWorkspaceGitRoot: boolean, output: Log, consistency?: BindMountConsistency, overrideConfigFile?: URI) {
+export async function readDevContainerConfigFile(cliHost: CLIHost, workspace: Workspace | undefined, configFile: URI, mountWorkspaceGitRoot: boolean, mountGitWorktreeCommonDir: boolean, output: Log, consistency?: BindMountConsistency, overrideConfigFile?: URI) {
 	const documents = createDocuments(cliHost);
 	const content = await documents.readDocument(overrideConfigFile ?? configFile);
 	if (!content) {
@@ -90,7 +90,7 @@ export async function readDevContainerConfigFile(cliHost: CLIHost, workspace: Wo
 	if (!updated || typeof updated !== 'object' || Array.isArray(updated)) {
 		throw new ContainerError({ description: `Dev container config (${uriToFsPath(configFile, cliHost.platform)}) must contain a JSON object literal.` });
 	}
-	const workspaceConfig = await getWorkspaceConfiguration(cliHost, workspace, updated, mountWorkspaceGitRoot, output, consistency);
+	const workspaceConfig = await getWorkspaceConfiguration(cliHost, workspace, updated, mountWorkspaceGitRoot, mountGitWorktreeCommonDir, output, consistency);
 	const substitute0: SubstituteConfig = value => substitute({
 		platform: cliHost.platform,
 		localWorkspaceFolder: workspace?.rootFolderPath,

src/spec-node/devContainers.ts

@@ -30,6 +30,7 @@ export interface ProvisionOptions {
 	workspaceMountConsistency?: BindMountConsistency;
 	gpuAvailability?: GPUAvailability;
 	mountWorkspaceGitRoot: boolean;
+	mountGitWorktreeCommonDir: boolean;
 	configFile: URI | undefined;
 	overrideConfigFile: URI | undefined;
 	logLevel: LogLevel;
@@ -102,7 +103,7 @@ export async function launch(options: ProvisionOptions, providedIdLabels: string
 }
 
 export async function createDockerParams(options: ProvisionOptions, disposables: (() => Promise<unknown> | undefined)[]): Promise<DockerResolverParameters> {
-	const { persistedFolder, additionalMounts, updateRemoteUserUIDDefault, containerDataFolder, containerSystemDataFolder, workspaceMountConsistency, gpuAvailability, mountWorkspaceGitRoot, remoteEnv, experimentalLockfile, experimentalFrozenLockfile, omitLoggerHeader, secretsP } = options;
+	const { persistedFolder, additionalMounts, updateRemoteUserUIDDefault, containerDataFolder, containerSystemDataFolder, workspaceMountConsistency, gpuAvailability, mountWorkspaceGitRoot, mountGitWorktreeCommonDir, remoteEnv, experimentalLockfile, experimentalFrozenLockfile, omitLoggerHeader, secretsP } = options;
 	let parsedAuthority: DevContainerAuthority | undefined;
 	if (options.workspaceFolder) {
 		parsedAuthority = { hostPath: options.workspaceFolder } as DevContainerAuthority;
@@ -225,6 +226,7 @@ export async function createDockerParams(options: ProvisionOptions, disposables:
 		workspaceMountConsistencyDefault: workspaceMountConsistency,
 		gpuAvailability: gpuAvailability || 'detect',
 		mountWorkspaceGitRoot,
+		mountGitWorktreeCommonDir,
 		updateRemoteUserUIDOnMacOS: false,
 		cacheMount: 'bind',
 		removeOnStartup: options.removeExistingContainer,

src/spec-node/devContainersSpecCLI.ts

@@ -107,6 +107,7 @@ function provisionOptions(y: Argv) {
 		'workspace-mount-consistency': { choices: ['consistent' as 'consistent', 'cached' as 'cached', 'delegated' as 'delegated'], default: 'cached' as 'cached', description: 'Workspace mount consistency.' },
 		'gpu-availability': { choices: ['all' as 'all', 'detect' as 'detect', 'none' as 'none'], default: 'detect' as 'detect', description: 'Availability of GPUs in case the dev container requires any. `all` expects a GPU to be available.' },
 		'mount-workspace-git-root': { type: 'boolean', default: true, description: 'Mount the workspace using its Git root.' },
+		'mount-git-worktree-common-dir': { type: 'boolean', default: false, description: 'Mount the Git worktree common dir for Git operations to work in the container. This requires the worktree to be created with relative paths (`git worktree add --relative-paths`).' },
 		'id-label': { type: 'string', description: 'Id label(s) of the format name=value. These will be set on the container and used to query for an existing container. If no --id-label is given, one will be inferred from the --workspace-folder path.' },
 		'config': { type: 'string', description: 'devcontainer.json path. The default is to use .devcontainer/devcontainer.json or, if that does not exist, .devcontainer.json in the workspace folder.' },
 		'override-config': { type: 'string', description: 'devcontainer.json path to override any devcontainer.json in the workspace folder (or built-in configuration). This is required when there is no devcontainer.json otherwise.' },
@@ -182,6 +183,7 @@ async function provision({
 	'workspace-mount-consistency': workspaceMountConsistency,
 	'gpu-availability': gpuAvailability,
 	'mount-workspace-git-root': mountWorkspaceGitRoot,
+	'mount-git-worktree-common-dir': mountGitWorktreeCommonDir,
 	'id-label': idLabel,
 	config,
 	'override-config': overrideConfig,
@@ -237,6 +239,7 @@ async function provision({
 		workspaceMountConsistency,
 		gpuAvailability,
 		mountWorkspaceGitRoot,
+		mountGitWorktreeCommonDir,
 		configFile: config ? URI.file(path.resolve(process.cwd(), config)) : undefined,
 		overrideConfigFile: overrideConfig ? URI.file(path.resolve(process.cwd(), overrideConfig)) : undefined,
 		logLevel: mapLogLevel(logLevel),
@@ -420,6 +423,7 @@ async function doSetUp({
 			containerSystemDataFolder,
 			workspaceFolder: undefined,
 			mountWorkspaceGitRoot: false,
+			mountGitWorktreeCommonDir: false,
 			configFile,
 			overrideConfigFile: undefined,
 			logLevel: mapLogLevel(logLevel),
@@ -456,7 +460,7 @@ async function doSetUp({
 
 		const { common } = params;
 		const { cliHost, output } = common;
-		const configs = configFile && await readDevContainerConfigFile(cliHost, undefined, configFile, params.mountWorkspaceGitRoot, output, undefined, undefined);
+		const configs = configFile && await readDevContainerConfigFile(cliHost, undefined, configFile, params.mountWorkspaceGitRoot, params.mountGitWorktreeCommonDir, output, undefined, undefined);
 		if (configFile && !configs) {
 			throw new ContainerError({ description: `Dev container config (${uriToFsPath(configFile, cliHost.platform)}) not found.` });
 		}
@@ -586,6 +590,7 @@ async function doBuild({
 			containerSystemDataFolder: undefined,
 			workspaceFolder,
 			mountWorkspaceGitRoot: false,
+			mountGitWorktreeCommonDir: false,
 			configFile,
 			overrideConfigFile,
 			logLevel: mapLogLevel(logLevel),
@@ -626,7 +631,7 @@ async function doBuild({
 			? (await getDevContainerConfigPathIn(cliHost, workspace.configFolderPath)
 				|| (overrideConfigFile ? getDefaultDevContainerConfigPath(cliHost, workspace.configFolderPath) : undefined))
 			: overrideConfigFile;
-		const configs = configPath && await readDevContainerConfigFile(cliHost, workspace, configPath, params.mountWorkspaceGitRoot, output, undefined, overrideConfigFile) || undefined;
+		const configs = configPath && await readDevContainerConfigFile(cliHost, workspace, configPath, params.mountWorkspaceGitRoot, params.mountGitWorktreeCommonDir, output, undefined, overrideConfigFile) || undefined;
 		if (!configs) {
 			throw new ContainerError({ description: `Dev container config (${uriToFsPath(configFile || getDefaultDevContainerConfigPath(cliHost, workspace!.configFolderPath), cliHost.platform)}) not found.` });
 		}
@@ -754,6 +759,7 @@ function runUserCommandsOptions(y: Argv) {
 		'container-system-data-folder': { type: 'string', description: 'Container system data folder where system data inside the container will be stored.' },
 		'workspace-folder': { type: 'string', description: 'Workspace folder path. The devcontainer.json will be looked up relative to this path.' },
 		'mount-workspace-git-root': { type: 'boolean', default: true, description: 'Mount the workspace using its Git root.' },
+		'mount-git-worktree-common-dir': { type: 'boolean', default: false, description: 'Mount the Git worktree common dir for Git operations to work in the container. This requires the worktree to be created with relative paths (`git worktree add --relative-paths`).' },
 		'container-id': { type: 'string', description: 'Id of the container to run the user commands for.' },
 		'id-label': { type: 'string', description: 'Id label(s) of the format name=value. If no --container-id is given the id labels will be used to look up the container. If no --id-label is given, one will be inferred from the --workspace-folder path.' },
 		'config': { type: 'string', description: 'devcontainer.json path. The default is to use .devcontainer/devcontainer.json or, if that does not exist, .devcontainer.json in the workspace folder.' },
@@ -814,6 +820,7 @@ async function doRunUserCommands({
 	'container-system-data-folder': containerSystemDataFolder,
 	'workspace-folder': workspaceFolderArg,
 	'mount-workspace-git-root': mountWorkspaceGitRoot,
+	'mount-git-worktree-common-dir': mountGitWorktreeCommonDir,
 	'container-id': containerId,
 	'id-label': idLabel,
 	config: configParam,
@@ -857,6 +864,7 @@ async function doRunUserCommands({
 			containerSystemDataFolder,
 			workspaceFolder,
 			mountWorkspaceGitRoot,
+			mountGitWorktreeCommonDir,
 			configFile,
 			overrideConfigFile,
 			logLevel: mapLogLevel(logLevel),
@@ -900,7 +908,7 @@ async function doRunUserCommands({
 			? (await getDevContainerConfigPathIn(cliHost, workspace.configFolderPath)
 				|| (overrideConfigFile ? getDefaultDevContainerConfigPath(cliHost, workspace.configFolderPath) : undefined))
 			: overrideConfigFile;
-		const configs = configPath && await readDevContainerConfigFile(cliHost, workspace, configPath, params.mountWorkspaceGitRoot, output, undefined, overrideConfigFile) || undefined;
+		const configs = configPath && await readDevContainerConfigFile(cliHost, workspace, configPath, params.mountWorkspaceGitRoot, params.mountGitWorktreeCommonDir, output, undefined, overrideConfigFile) || undefined;
 		if ((configFile || workspaceFolder || overrideConfigFile) && !configs) {
 			throw new ContainerError({ description: `Dev container config (${uriToFsPath(configFile || getDefaultDevContainerConfigPath(cliHost, workspace!.configFolderPath), cliHost.platform)}) not found.` });
 		}
@@ -956,6 +964,7 @@ function readConfigurationOptions(y: Argv) {
 		'docker-compose-path': { type: 'string', description: 'Docker Compose CLI path.' },
 		'workspace-folder': { type: 'string', description: 'Workspace folder path. The devcontainer.json will be looked up relative to this path.' },
 		'mount-workspace-git-root': { type: 'boolean', default: true, description: 'Mount the workspace using its Git root.' },
+		'mount-git-worktree-common-dir': { type: 'boolean', default: false, description: 'Mount the Git worktree common dir for Git operations to work in the container. This requires the worktree to be created with relative paths (`git worktree add --relative-paths`).' },
 		'container-id': { type: 'string', description: 'Id of the container to run the user commands for.' },
 		'id-label': { type: 'string', description: 'Id label(s) of the format name=value. If no --container-id is given the id labels will be used to look up the container. If no --id-label is given, one will be inferred from the --workspace-folder path.' },
 		'config': { type: 'string', description: 'devcontainer.json path. The default is to use .devcontainer/devcontainer.json or, if that does not exist, .devcontainer.json in the workspace folder.' },
@@ -993,6 +1002,7 @@ async function readConfiguration({
 	'docker-compose-path': dockerComposePath,
 	'workspace-folder': workspaceFolderArg,
 	'mount-workspace-git-root': mountWorkspaceGitRoot,
+	'mount-git-worktree-common-dir': mountGitWorktreeCommonDir,
 	config: configParam,
 	'override-config': overrideConfig,
 	'container-id': containerId,
@@ -1033,7 +1043,7 @@ async function readConfiguration({
 			? (await getDevContainerConfigPathIn(cliHost, workspace.configFolderPath)
 				|| (overrideConfigFile ? getDefaultDevContainerConfigPath(cliHost, workspace.configFolderPath) : undefined))
 			: overrideConfigFile;
-		const configs = configPath && await readDevContainerConfigFile(cliHost, workspace, configPath, mountWorkspaceGitRoot, output, undefined, overrideConfigFile) || undefined;
+		const configs = configPath && await readDevContainerConfigFile(cliHost, workspace, configPath, mountWorkspaceGitRoot, mountGitWorktreeCommonDir, output, undefined, overrideConfigFile) || undefined;
 		if ((configFile || workspaceFolder || overrideConfigFile) && !configs) {
 			throw new ContainerError({ description: `Dev container config (${uriToFsPath(configFile || getDefaultDevContainerConfigPath(cliHost, workspace!.configFolderPath), cliHost.platform)}) not found.` });
 		}
@@ -1154,7 +1164,7 @@ async function outdated({
 
 		const workspace = workspaceFromPath(cliHost.path, workspaceFolder);
 		const configPath = configFile ? configFile : await getDevContainerConfigPathIn(cliHost, workspace.configFolderPath);
-		const configs = configPath && await readDevContainerConfigFile(cliHost, workspace, configPath, true, output) || undefined;
+		const configs = configPath && await readDevContainerConfigFile(cliHost, workspace, configPath, true, false, output) || undefined;
 		if (!configs) {
 			throw new ContainerError({ description: `Dev container config (${uriToFsPath(configFile || getDefaultDevContainerConfigPath(cliHost, workspace!.configFolderPath), cliHost.platform)}) not found.` });
 		}
@@ -1211,6 +1221,7 @@ function execOptions(y: Argv) {
 		'container-system-data-folder': { type: 'string', description: 'Container system data folder where system data inside the container will be stored.' },
 		'workspace-folder': { type: 'string', description: 'Workspace folder path. The devcontainer.json will be looked up relative to this path.' },
 		'mount-workspace-git-root': { type: 'boolean', default: true, description: 'Mount the workspace using its Git root.' },
+		'mount-git-worktree-common-dir': { type: 'boolean', default: false, description: 'Mount the Git worktree common dir for Git operations to work in the container. This requires the worktree to be created with relative paths (`git worktree add --relative-paths`).' },
 		'container-id': { type: 'string', description: 'Id of the container to run the user commands for.' },
 		'id-label': { type: 'string', description: 'Id label(s) of the format name=value. If no --container-id is given the id labels will be used to look up the container. If no --id-label is given, one will be inferred from the --workspace-folder path.' },
 		'config': { type: 'string', description: 'devcontainer.json path. The default is to use .devcontainer/devcontainer.json or, if that does not exist, .devcontainer.json in the workspace folder.' },
@@ -1272,6 +1283,7 @@ export async function doExec({
 	'container-system-data-folder': containerSystemDataFolder,
 	'workspace-folder': workspaceFolderArg,
 	'mount-workspace-git-root': mountWorkspaceGitRoot,
+	'mount-git-worktree-common-dir': mountGitWorktreeCommonDir,
 	'container-id': containerId,
 	'id-label': idLabel,
 	config: configParam,
@@ -1304,6 +1316,7 @@ export async function doExec({
 			containerSystemDataFolder,
 			workspaceFolder,
 			mountWorkspaceGitRoot,
+			mountGitWorktreeCommonDir,
 			configFile,
 			overrideConfigFile,
 			logLevel: mapLogLevel(logLevel),
@@ -1344,7 +1357,7 @@ export async function doExec({
 			? (await getDevContainerConfigPathIn(cliHost, workspace.configFolderPath)
 				|| (overrideConfigFile ? getDefaultDevContainerConfigPath(cliHost, workspace.configFolderPath) : undefined))
 			: overrideConfigFile;
-		const configs = configPath && await readDevContainerConfigFile(cliHost, workspace, configPath, params.mountWorkspaceGitRoot, output, undefined, overrideConfigFile) || undefined;
+		const configs = configPath && await readDevContainerConfigFile(cliHost, workspace, configPath, params.mountWorkspaceGitRoot, params.mountGitWorktreeCommonDir, output, undefined, overrideConfigFile) || undefined;
 		if ((configFile || workspaceFolder || overrideConfigFile) && !configs) {
 			throw new ContainerError({ description: `Dev container config (${uriToFsPath(configFile || getDefaultDevContainerConfigPath(cliHost, workspace!.configFolderPath), cliHost.platform)}) not found.` });
 		}

src/spec-node/featuresCLI/resolveDependencies.ts

@@ -77,7 +77,7 @@ async function featuresResolveDependencies({
 	const cliHost = await getCLIHost(cwd, loadNativeModule, true);
 	const workspace = workspaceFromPath(cliHost.path, workspaceFolder);
 	const configFile: URI = URI.file(path.resolve(process.cwd(), configPath));
-	const configs = await readDevContainerConfigFile(cliHost, workspace, configFile, false, output, undefined, undefined);	
+	const configs = await readDevContainerConfigFile(cliHost, workspace, configFile, false, false, output, undefined, undefined);
 
 	if (configFile && !configs) {
 		throw new ContainerError({ description: `Dev container config (${uriToFsPath(configFile, cliHost.platform)}) not found.` });

src/spec-node/featuresCLI/testCommandImpl.ts

@@ -553,6 +553,7 @@ async function launchProject(params: DockerResolverParameters, workspaceFolder:
 		additionalLabels: [],
 		logLevel: common.getLogLevel(),
 		mountWorkspaceGitRoot: true,
+		mountGitWorktreeCommonDir: false,
 		remoteEnv: common.remoteEnv,
 		skipFeatureAutoMapping: common.skipFeatureAutoMapping,
 		skipPersistingCustomizationsFromFeatures: common.skipPersistingCustomizationsFromFeatures,
@@ -632,6 +633,7 @@ async function generateDockerParams(workspaceFolder: string, args: FeaturesTestC
 		containerDataFolder: undefined,
 		containerSystemDataFolder: undefined,
 		mountWorkspaceGitRoot: false,
+		mountGitWorktreeCommonDir: false,
 		configFile: undefined,
 		overrideConfigFile: undefined,
 		logLevel,

src/spec-node/featuresCLI/utils.ts

@@ -40,6 +40,7 @@ export const staticExecParams = {
     'terminal-columns': undefined,
     'container-id': undefined,
     'mount-workspace-git-root': true,
+    'mount-git-worktree-common-dir': false,
     'log-level': 'info' as 'info',
     'log-format': 'text' as 'text',
     'default-user-env-probe': 'loginInteractiveShell' as 'loginInteractiveShell',