Add extendsMergeMode for combine vs override extends merging

Optional extendsMergeMode on devcontainer.json selects image-metadata
combine (default) or overlay-style override when resolving extends.

Author: SamuelFrost

CHANGELOG.md

@@ -4,7 +4,7 @@ Notable changes.
 
 ## Unreleased
 
-- Add support for the `extends` keyword so one `devcontainer.json` can inherit another using the image metadata merge logic. (https://github.com/devcontainers/spec/issues/22, https://github.com/devcontainers/cli/pull/311)
+- Add support for the `extends` keyword so one `devcontainer.json` can inherit another, with optional `extendsMergeMode` (`combine` uses image metadata merge logic; `override` replaces arrays/scalars from the child). (https://github.com/devcontainers/spec/issues/22, https://github.com/devcontainers/cli/pull/311)
 
 ## August 2026
 

src/spec-configuration/configuration.ts

@@ -21,6 +21,8 @@ export type UserEnvProbe = 'none' | 'loginInteractiveShell' | 'interactiveShell'
 
 export type DevContainerConfigCommand = 'initializeCommand' | 'onCreateCommand' | 'updateContentCommand' | 'postCreateCommand' | 'postStartCommand' | 'postAttachCommand';
 
+export type DevContainerExtendsMergeMode = 'combine' | 'override';
+
 export interface HostGPURequirements {
 	cores?: number;
 	memory?: string;
@@ -74,6 +76,7 @@ export interface DevContainerFromImageConfig {
 	overrideFeatureInstallOrder?: string[];
 	hostRequirements?: HostRequirements;
 	extends?: string;
+	extendsMergeMode?: DevContainerExtendsMergeMode;
 	customizations?: Record<string, any>;
 }
 
@@ -112,6 +115,7 @@ export type DevContainerFromDockerfileConfig = {
 	overrideFeatureInstallOrder?: string[];
 	hostRequirements?: HostRequirements;
 	extends?: string;
+	extendsMergeMode?: DevContainerExtendsMergeMode;
 	customizations?: Record<string, any>;
 } & (
 		{
@@ -171,6 +175,7 @@ export interface DevContainerFromDockerComposeConfig {
 	overrideFeatureInstallOrder?: string[];
 	hostRequirements?: HostRequirements;
 	extends?: string;
+	extendsMergeMode?: DevContainerExtendsMergeMode;
 	customizations?: Record<string, any>;
 }
 

src/spec-node/configContainer.ts

@@ -99,13 +99,18 @@ async function readDevContainerConfigObject(cliHost: CLIHost, configUri: URI, se
 	}
 
 	const extendsPath = updated.extends;
+	const extendsMergeMode = updated.extendsMergeMode ?? 'combine';
 	delete updated.extends;
+	delete updated.extendsMergeMode;
 	if (!extendsPath) {
 		return updated;
 	}
 	if (typeof extendsPath !== 'string' || !extendsPath.trim()) {
 		throw new ContainerError({ description: `"extends" in (${uriToFsPath(configUri, cliHost.platform)}) must be a relative path to a JSON or JSONC file.` });
 	}
+	if (extendsMergeMode !== 'combine' && extendsMergeMode !== 'override') {
+		throw new ContainerError({ description: `"extendsMergeMode" in (${uriToFsPath(configUri, cliHost.platform)}) must be "combine" or "override".` });
+	}
 	if (cliHost.path.isAbsolute(extendsPath) || /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(extendsPath)) {
 		throw new ContainerError({ description: `"extends" in (${uriToFsPath(configUri, cliHost.platform)}) must be a relative path within the same repository.` });
 	}
@@ -115,7 +120,7 @@ async function readDevContainerConfigObject(cliHost: CLIHost, configUri: URI, se
 	if (!parent) {
 		throw new ContainerError({ description: `Dev container config extended from (${uriToFsPath(configUri, cliHost.platform)}) was not found: ${uriToFsPath(parentUri, cliHost.platform)}.` });
 	}
-	return mergeDevContainerConfigs(parent, updated);
+	return mergeDevContainerConfigs(parent, updated, extendsMergeMode);
 }
 
 export async function readDevContainerConfigFile(cliHost: CLIHost, workspace: Workspace | undefined, configFile: URI, mountWorkspaceGitRoot: boolean, mountGitWorktreeCommonDir: boolean, output: Log, consistency?: BindMountConsistency, overrideConfigFile?: URI) {

src/spec-node/imageMetadata.ts

@@ -6,7 +6,7 @@
 import { ContainerError } from '../spec-common/errors';
 import { PlatformInfo } from '../spec-common/commonUtils';
 import { LifecycleCommand, LifecycleHooksInstallMap } from '../spec-common/injectHeadless';
-import { DevContainerConfig, DevContainerConfigCommand, DevContainerFromDockerComposeConfig, DevContainerFromDockerfileConfig, DevContainerFromImageConfig, getDockerComposeFilePaths, getDockerfilePath, HostGPURequirements, HostRequirements, isDockerFileConfig, PortAttributes, UserEnvProbe } from '../spec-configuration/configuration';
+import { DevContainerConfig, DevContainerConfigCommand, DevContainerExtendsMergeMode, DevContainerFromDockerComposeConfig, DevContainerFromDockerfileConfig, DevContainerFromImageConfig, getDockerComposeFilePaths, getDockerfilePath, HostGPURequirements, HostRequirements, isDockerFileConfig, PortAttributes, UserEnvProbe } from '../spec-configuration/configuration';
 import { Feature, FeaturesConfig, Mount, parseMount, SchemaFeatureLifecycleHooks } from '../spec-configuration/containerFeaturesConfiguration';
 import { ContainerDetails, DockerCLIParameters, ImageDetails } from '../spec-shutdown/dockerUtils';
 import { Log, LogLevel } from '../spec-utils/log';
@@ -204,13 +204,18 @@ export function mergeConfiguration(config: DevContainerConfig, imageMetadata: Im
  * (https://containers.dev/implementors/spec/#merge-logic) so `extends` behaves the same as
  * combining a prebuilt image's metadata with a project's config.
  */
-export function mergeDevContainerConfigs(base: DevContainerConfig, overlay: DevContainerConfig): DevContainerConfig {
+export function mergeDevContainerConfigs(base: DevContainerConfig, overlay: DevContainerConfig, extendsMergeMode: DevContainerExtendsMergeMode = 'combine'): DevContainerConfig {
+	if (extendsMergeMode === 'override') {
+		return mergeDevContainerConfigsOverride(base, overlay);
+	}
+
 	const metadata: ImageMetadataEntry[] = [base, overlay];
 	const merged = {
 		...base,
 		...overlay,
 	} as DevContainerConfig;
 	delete merged.extends;
+	delete merged.extendsMergeMode;
 
 	if (base.init || overlay.init) {
 		merged.init = true;
@@ -266,6 +271,34 @@ export function mergeDevContainerConfigs(base: DevContainerConfig, overlay: DevC
 	return merged;
 }
 
+/**
+ * Overlay-style merge: scalars and arrays from the overlay replace the base when set;
+ * object maps and `hostRequirements` are shallow-merged with overlay keys winning.
+ */
+function mergeDevContainerConfigsOverride(base: DevContainerConfig, overlay: DevContainerConfig): DevContainerConfig {
+	const merged = {
+		...base,
+		...overlay,
+	} as DevContainerConfig;
+	delete merged.extends;
+	delete merged.extendsMergeMode;
+
+	const remoteEnv = Object.assign({}, base.remoteEnv, overlay.remoteEnv);
+	assignOrDelete(merged, 'remoteEnv', Object.keys(remoteEnv).length ? remoteEnv : undefined);
+	const containerEnv = Object.assign({}, base.containerEnv, overlay.containerEnv);
+	assignOrDelete(merged, 'containerEnv', Object.keys(containerEnv).length ? containerEnv : undefined);
+	const portsAttributes = Object.assign({}, base.portsAttributes, overlay.portsAttributes);
+	assignOrDelete(merged, 'portsAttributes', Object.keys(portsAttributes).length ? portsAttributes : undefined);
+	const features = Object.assign({}, base.features, overlay.features);
+	assignOrDelete(merged, 'features', Object.keys(features).length ? features : undefined);
+	const customizations = Object.assign({}, base.customizations, overlay.customizations);
+	assignOrDelete(merged, 'customizations', Object.keys(customizations).length ? customizations : undefined);
+	const hostRequirements = Object.assign({}, base.hostRequirements, overlay.hostRequirements);
+	assignOrDelete(merged, 'hostRequirements', Object.keys(hostRequirements).length ? hostRequirements : undefined);
+
+	return merged;
+}
+
 function assignOrDelete<K extends keyof DevContainerConfig>(target: DevContainerConfig, key: K, value: DevContainerConfig[K] | undefined) {
 	if (value !== undefined) {
 		target[key] = value;