From e5f0d2cb764388a5b419bbd84f479e598a56e924 Mon Sep 17 00:00:00 2001 From: Josh Spicer false Date: Thu, 5 Sep 2024 10:54:27 -0700 Subject: [PATCH] sync optionalPaths addition with spec (https://github.com/devcontainers/spec/pull/484) --- _implementors/templates.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/_implementors/templates.md b/_implementors/templates.md index 9e12eff2..681a48c8 100644 --- a/_implementors/templates.md +++ b/_implementors/templates.md @@ -37,10 +37,11 @@ The properties of the file are as follows: | `description` | string | Description of the Template. | | `documentationURL` | string | Url that points to the documentation of the Template. | | `licenseURL` | string | Url that points to the license of the Template. | -| `options` | object | A map of options that the supporting tools should use to populate different configuration options for the Template. | +| [`options`](#options) | object | A map of options that the supporting tools should use to populate different configuration options for the Template. | | `platforms` | array | Languages and platforms supported by the Template. | | `publisher` | string | Name of the publisher/maintainer of the Template. | | `keywords` | array | List of strings relevant to a user that would search for this Template. | +| [`optionalPaths`](#optionalPaths) | array | An array of files or directories that tooling may consider "optional" when applying a Template. Directories are indicated with a trailing `/*`, (eg: `.github/*`). {: .table .table-bordered .table-responsive} ### The `options` property @@ -71,6 +72,30 @@ The `options` property contains a map of option IDs and their related configurat > `Note`: The `options` must be unique for every `devcontainer-template.json` +### The `optionalPaths` property + +Before applying a Template, tooling must inspect the `optionalPaths` property of a Template and prompt the user on whether each file or folder should be included in the resulting output workspace folder. A path is relative to the root of the Template source directory. + +- For a single file, provide the full relative path (without any leading or trailing path delimiters). +- For a directory, provide the full relative path with a trailing slash and asterisk (`/*`) appended to the path. The directory and its children will be recursively ignored. + +Examples are shown below: + +```jsonc +{ + "id": "cpp", + "version": "3.0.0", + "name": "C++", + "description": "Develop C++ applications", + "optionalPaths": [ + "GETTING-STARTED.md", // Single file + "example-project-1/MyProject.csproj", // Single file in nested directory + ".github/*" // Entire recursive contents of directory + ] +} +``` + + ### Referencing a Template The `id` format (`//