Document handling of multiple and missing profiles

[ekatko1]

What would you like to do?

Give feedback or suggest an improvement

Description

If multiple profiles are supplied, but different profiles contain different configurations for the same key, what happens?

If one of the supplied profiles is missing, does it simply get ignored ? Also see #13368

Thanks!

[cderv]

Thanks for the questions.

I moved you question to discussions which we prefer to use for such questions.

Multiple profiles with conflicting keys

Profiles are merged in order with the first-listed profile taking priority. The relevant code:

quarto-cli/src/project/project-profile.ts

Lines 171 to 179 in 45ecb6e

	// merge all active profiles (reverse order so first gets priority)
	for (const profileName of activeProfiles().reverse()) {
	const profilePath = [".yml", ".yaml"].map((
	ext,
	) => join(dir, `_quarto-${profileName}${ext}`)).find(safeExistsSync);
	if (profilePath) {
	await mergeProfile(profilePath);
	}
	}

The merge semantics mirror the general metadata merging (https://quarto.org/docs/projects/quarto-projects.html#metadata-merging) behavior:

• Scalar values: first-listed profile wins. With --profile production,advanced, if both define execute.freeze for example, the production value takes effect.
• Arrays: union-concatenated and deduplicated across all active profiles.
• Objects: deep-merged (leaf keys from all profiles are combined).

Missing profiles

Yes, a missing profile is silently ignored. If _quarto-{name}.yml and _quarto-{name}.yaml don't exist in the project directory, that profile name is skipped with no warning
or error. This is a known gap — #13368 proposes adding a lint warning for exactly this case.

I'll try to update the doc to add info on those.