Update README with "How to use Templates" section (#241)

* Update README with "How to use Templates" section * Update README.md Co-authored-by: Brigit Murtaugh <[email protected]> * Update README.md Co-authored-by: Brigit Murtaugh <[email protected]> * Update README.md Co-authored-by: Brigit Murtaugh <[email protected]> * Update README.md Co-authored-by: Brigit Murtaugh <[email protected]> --------- Co-authored-by: Brigit Murtaugh <[email protected]>
devcontainers · Feb 26, 2024 · 3debff2 · 3debff2
1 parent d9b9815
commit 3debff2
Show file tree

Hide file tree

Showing 2 changed files with 50 additions and 0 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,12 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for more information:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+# https://containers.dev/guide/dependabot
+
+version: 2
+updates:
+ - package-ecosystem: "devcontainers"
+   directory: "/"
+   schedule:
+     interval: weekly
diff --git a/README.md b/README.md
@@ -19,6 +19,44 @@ This repository contains a set of **Dev Container Templates** which are source f
     `devcontainer-template.json` and a [devcontainer.json](https://containers.dev/implementors/json_reference/).
 -   [`test`](test) - Mirroring `src`, a folder-per-template with at least a `test.sh` script. These tests are executed by the [CI](https://github.com/devcontainers/templates/blob/main/.github/workflows/test-pr.yaml).
 
+## How can I use the Templates?
+
+### 1. Using supporting tools
+
+A variety of tools and services [support](https://containers.dev/supporting) the Dev Container Spec, and they may provide direct integrations with the Templates in this repo. For instance, [Visual Studio Code](https://code.visualstudio.com/) and [GitHub Codespaces](https://docs.github.com/en/codespaces/overview) provide a user-friendly interface to configure the Templates hosted in this repository, as well as the [community-contributed Templates](https://containers.dev/templates). Additionally, you can customize your dev container with additional available [Features](https://containers.dev/features).
+
+For more information, please refer to the following documents for [VS Code](https://code.visualstudio.com/docs/devcontainers/create-dev-container#_automate-dev-container-creation) and [Github Codespaces](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#using-a-predefined-dev-container-configuration).
+
+### 2. Using the Dev Container CLI
+
+The [@devcontainers/cli](https://containers.dev/supporting#devcontainer-cli) offers a `devcontainer templates apply` command to apply a Template hosted in the supported OCI registry.
+
+```
+devcontainer templates apply
+
+Apply a template to the project
+
+Options:
+      --help              Show help                                                                            [boolean]
+      --version           Show version number                                                                  [boolean]
+  -w, --workspace-folder  Target workspace folder to apply Template                   [string] [required] [default: "."]
+  -t, --template-id       Reference to a Template in a supported OCI registry                        [string] [required]
+  -a, --template-args     Arguments to replace within the provided Template, provided as JSON   [string] [default: "{}"]
+  -f, --features          Features to add to the provided Template, provided as JSON.           [string] [default: "[]"]
+      --log-level         Log level.                               [choices: "info", "debug", "trace"] [default: "info"]
+      --tmp-dir           Directory to use for temporary files. If not provided, the system default will be inferred.
+                                                                                                                [string]
+```
+
+#### Example
+
+```
+devcontainer templates apply --workspace-folder . \
+    --template-id ghcr.io/devcontainers/templates/cpp:latest \
+    --template-args '{ "imageVariant": "debian-12" }' \
+    --features '[{ "id": "ghcr.io/devcontainers/features/azure-cli:1", "options": { "version" : "1" } }]'
+```
+
 ## Contributions
 
 ### Creating your own collection of templates