From 8d793c719085c8ab5f0f4850d408a81c38b0e209 Mon Sep 17 00:00:00 2001
From: Josh Spicer <josh@joshspicer.com>
Date: Thu, 26 Sep 2024 12:02:27 -0700
Subject: [PATCH] sync optionalPaths addition with spec
 (https://github.com/devcontainers/spec/pull/484) (#459)

---
 _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}
 
 ### <a href="#options" name="options" class="anchor">  The `options` property</a>
@@ -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`
 
+### <a href="#optionalPaths" name="optionalPaths" class="anchor">  The `optionalPaths` property</a>
+
+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
+     ]
+}
+```
+
+
 ### <a href="#referencing-a-template" name="referencing-a-template" class="anchor"> Referencing a Template </a>
 
 The `id` format (`<oci-registry>/<namespace>/<template>[:<semantic-version>]`) dictates how a [supporting tool](/supporting) will locate and download a given Template from an OCI registry. For example: