Skip to content

Commit f8a4edc

Browse files
stuartleeksstuartleeks
committed
Update docs
1 parent cbfe4b4 commit f8a4edc

1 file changed

Lines changed: 116 additions & 13 deletions

File tree

‎docs/snippet.md‎

Lines changed: 116 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,50 @@
11
# devcontainer snippet ...
22

3-
***WARNING: This feature is experimental***
3+
***WARNING: This feature is experimental!***
44

55
{:toc}
66

7-
87
## Setting up snippets
98

10-
119
To use the `devcontainer snippet` commands you need to enable experimental feaaures and configure some snippet folders.
1210

13-
A snippet folder can be as simple as a set of `.sh` scripts - examples can be found in the `snippets` folder of [stuartleeks/devcontainers](https://github.com/stuartleeks/devcontainers).
11+
A snippet collection can be as simple as a set of `.sh` scripts. Good starting points for snippets are the `snippets` folder of [stuartleeks/devcontainers](https://github.com/stuartleeks/devcontainers) and [benc-uk/tools-install](https://github.com/benc-uk/tools-install/).
12+
13+
Choose a directory to put the snippets in, and clone the repos:
1414

15-
Choose a directory, and clone the repo using `git clone https://github.com/stuartleeks/devcontainers`
15+
```bash
16+
git clone https://github.com/stuartleeks/devcontainers
17+
git clone https://github.com/benc-uk/tools-install/
18+
```
1619

17-
Next, we need to tell the `devcontainer` CLI to use this folder. If you haven't previously created a config file, run `devcontainer config write` to save a config file and then open `~/.devcontainer-cli/devcontainer-cli.json` in your favourite editor.
20+
Next, we need to tell the `devcontainer` CLI to use these folders. If you haven't previously created a config file, run `devcontainer config write` to save a config file and then open `~/.devcontainer-cli/devcontainer-cli.json` in your favourite editor.
1821

1922
The starting configuration will look something like:
2023

2124
```json
2225
{
23-
"templatepaths": []
26+
"templatepaths": []
2427
}
2528
```
2629

27-
Add an `experimental` setting with the value `true` to turn on experimental features, and add a `snippetpaths` setting with an array value containing the path to your snippet folder, e.g.:
30+
Add a `snippetpaths` setting with an array value containing the path to your snippet folders. For example, if you cloned the repos into your `~/source` folder add the following to your config file:
2831

2932
```json
3033
{
31-
"experimental" : true,
32-
"snippetpaths": ["$HOME/source/sl-devcontainers/snippets"]
34+
"experimental" : true,
35+
"snippetpaths": ["$HOME/source/sl-devcontainers/snippets", "$HOME/source/tools-install"]
3336
}
3437
```
3538

39+
NOTE: You also need to add the `experimental` setting with the value `true` as snippets are currently an experimental features
40+
3641
## Listing snippets
3742

3843
Running `devcontainer snippet list` will show the snippets that `devcontainer` discovered
3944

4045
## Adding a snippet
4146

42-
To add a snippet to the dev container definition to your project, change directory to the project folder (i.e. the one with the `.devcontainer` folder) and then run:
47+
To add a snippet to the dev container definition to your project, change directory to the project folder (i.e. the one containing the `.devcontainer` folder) and then run:
4348

4449
```bash
4550
# Add the azbrowse
@@ -48,6 +53,104 @@ devcontainer snippet add azbrowse
4853

4954
This will copy in the snippet files for you to modify as you wish.
5055

51-
## Creating your own snippets **TODO**
56+
## Creating your own snippets
57+
58+
`devcontainer` can be configured to scan multiple folders to find snippets. For each folder configured in the `snippetpaths` setting it searches for snippets. There are currently two types of snippet supported: single file snippets and folder-based snippets.
59+
60+
### Single file snippets
61+
62+
Single file snippets are `.sh` files that are copied to the `.devcontainer/scripts` folder and added to the `Dockerfile`. This is the simplest place to start when creating a snippet.
63+
64+
### Folder-based snippets
65+
66+
Folder-based snippets are folders containing a `snippet.json` file. The `snippet.json` describes the actions to take when applying the snippet, for example:
67+
68+
```json
69+
{
70+
"actions": [
71+
{
72+
"type" : "copyAndRun",
73+
"source": "my-script.sh"
74+
}
75+
]
76+
}
77+
```
78+
79+
The `actions` property can contain multiple actions and they are applied in order.
80+
81+
The following action types are supported:
82+
83+
- `copyAndRun`
84+
- `mergeJSON`
85+
- `dockerfileSnippet`
86+
87+
#### copyAndRun action
88+
89+
The `copyAndRun` action provides the same capability as the single file snippet, i.e. the source file is copied and added to the `Dockerfile`.
90+
91+
The following properties are supported for a `copyAndRun` action:
92+
93+
| Property | Description |
94+
|----------|--------------------------------------------------------------------|
95+
| source | The path to the script file to copy (relative to the snippet.json) |
96+
97+
For example:
5298

53-
`devcontainer` can be configured to scan multiple folders to find snippets. For each folder configured in the `snippetpaths` setting it searches for `*.sh` files.
99+
```json
100+
{
101+
"actions": [
102+
{
103+
"type": "copyAndRun",
104+
"source": "golang.sh"
105+
}
106+
]
107+
}
108+
```
109+
110+
#### mergeJSON action
111+
112+
The `mergeJSON` action provides the ability to merge changes into a JSON file (e.g. `devcontainer.json`).
113+
114+
The following properties are supported for a `mergeJSON` action:
115+
116+
| Property | Description |
117+
|----------|-------------------------------------------------------------------------------|
118+
| source | The path to the JSON file containing the properties to merge in to the target |
119+
| target | The path to the JSON file to merge the changes into |
120+
121+
For example:
122+
123+
```json
124+
{
125+
"actions": [
126+
{
127+
"type": "mergeJSON",
128+
"source": "devcontainer.json",
129+
"target": ".devcontainer/devcontainer.json"
130+
}
131+
]
132+
}
133+
```
134+
135+
#### dockerfileSnippet action
136+
137+
The `dockerfileSnippet` action provides a way to add custom steps to the `Dockerfile` for a dev container.
138+
139+
The following properties are supported for a `dockerfileSnippet` action:
140+
141+
| Property | Description |
142+
|----------|--------------------------------------|
143+
| content | The content to add to the Dockerfile |
144+
145+
For example:
146+
147+
```json
148+
{
149+
"actions": [
150+
{
151+
"type": "dockerfileSnippet",
152+
"content": "# Add go to PATH\nENV PATH /usr/local/go/bin:$PATH"
153+
}
154+
]
155+
}
156+
```

0 commit comments

Comments
 (0)