Skip to content

Commit 707bfe2

Browse files
stuartleeksstuartleeks
committed
Initial content
1 parent 3e80680 commit 707bfe2

File tree

5 files changed

+239
-2
lines changed

5 files changed

+239
-2
lines changed

‎docs/exec.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# devcontainer exec
2+
3+
The `devcontainer exec` command can be used to run commands inside a running dev container. When no options are passed, it will run `bash` in the dev container for the dev container for the current working directory.
4+
5+
Some examples of using `devcontainer exec` are shown below:
6+
7+
```bash
8+
# Run an interactive bash shell in the
9+
# vscode-remote-test-dockerfile devcontainer
10+
devcontainer exec --name vscode-remote-test-dockerfile bash
11+
12+
# Run a command with args in the
13+
# vscode-remote-test-dockercompose_devcontainer/mongo
14+
# devcontainer
15+
devcontainer exec --name vscode-remote-test-dockercompose_devcontainer/mongo ls -a /workspaces/vscode-remote-test-dockerfile
16+
17+
# Run `bash` in the dev container for
18+
# the project at `~/ source/my-proj`
19+
devcontainer exec --path ~/source/my-proj bash
20+
21+
# If none of --name/--path/--prompt
22+
# are specified then `--path .` is assumed
23+
# (i.e. use the dev container for the current directory)
24+
devcontainer exec bash
25+
26+
# If command/args not set, `bash` is assumed
27+
devcontainer exec --name vscode-remote-test-dockerfile
28+
29+
# Combining these to launch bash in the
30+
# dev container for the project in the current directory:
31+
devcontainer exec
32+
```
33+
34+
## Features of devcontainer exec
35+
36+
Under the covers, `devcontainer exec` launches `docker exec`, but it has a few features on top of this to try to increase productivity.
37+
38+
First, it sets the working directory to be the mount path for the dev container rather than just dropping you in at the root of the container flie system. This can be overridden using `--work-dir`.
39+
40+
Second, it checks whether you have [configured a user in the dev container](https://code.visualstudio.com/docs/remote/containers-advanced#_adding-a-nonroot-user-to-your-dev-container) and uses this user for the `docker exec`.
41+
42+
Lastly, it checks whether you have set up an SSH agent on your host. If you have and VS Code detects it then VS Code will [forward key requests from the container](https://code.visualstudio.com/docs/remote/containers#_using-ssh-keys). In this scenario, `devcontainer exec` configures the exec session to also forward key requests. This enables operations against git remotes secured with SSH keys to succeed.
43+
44+
45+
## Prompting for the dev container
46+
47+
48+
You can use `--prompt` with `devcontainer exec` instead of `--name` or `--path` and the CLI will prompt you to pick a devcontainer to run the `exec` command against, e.g.:
49+
50+
```bash
51+
$ ./devcontainer exec ? bash
52+
Specify the devcontainer to use:
53+
0: devcontainer-cli (festive_saha)
54+
1: vscode-remote-test-dockerfile (fervent_gopher)
55+
0
56+
```
57+
58+
This works well as a terminal profile. For example, you can use this with Windows Terminal profiles:
59+
60+
```json
61+
{
62+
"guid": "{4b304185-99d2-493c-940c-ae74e0f14bba}",
63+
"hidden": false,
64+
"name": "devcontainer exec",
65+
"commandline": "wsl bash -c \"path/to/devcontainer exec --prompt bash\"",
66+
},
67+
```

‎docs/index.md‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,31 @@
1-
# devcontainer CLI
1+
If you find frequently find yourself working at the terminal and are working with [Visual Studio Code dev containers](https://code.visualstudio.com/docs/remote/containers) then the `devcontainer` CLI might be of interest for you!
2+
3+
Examples:
4+
5+
```bash
6+
7+
# The following command opens the current folder in
8+
# VS Code as a dev container # i.e. it skips the
9+
# normal step of opening in VS Code and then
10+
# clicking # on the "Re-open in container" prompt.
11+
$ devcontainer open-in-code
12+
13+
# If you don't have a dev container definition for
14+
# your folder then you can use
15+
#`devcontainer template add <name>` to add a
16+
# dev container definition.
17+
$ devcontainer template add python-3
18+
19+
# You can use `devcontainer exec` to create a
20+
# shell (or run a process) # inside a dev container.
21+
$ devcontainer exec
22+
```
23+
24+
See the following topics for more information:
25+
26+
* [Installation](installation)
27+
* Commands
28+
* [open-in-code](open-in-code) - open dev containers in VS Code from the terminal
29+
* [template](template) - add dev container definitions to a folder
30+
* [exec](exec) - launch a terminal or other command in a dev container
231

3-
TODO - put content here

‎docs/installation.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Installation
2+
3+
4+
## Download latest release
5+
6+
Head to the [latest release page](https://github.com/stuartleeks/devcontainer-cli/releases/latest) and download the archive for your platform.
7+
8+
Extract `devcontainer` from the archive and place in a folder in your `PATH`.
9+
10+
## Homebrew
11+
12+
You can also install using `homebrew` with `brew install stuartleeks/tap/devcontainer`
13+
14+
## Just give me a script
15+
16+
Or if you just don't care and are happy to run random scripts from the internet:
17+
18+
```bash
19+
export OS=linux # also darwin
20+
export ARCH=amd64 # also 386
21+
wget https://raw.githubusercontent.com/stuartleeks/devcontainer-cli/main/scripts/install.sh
22+
chmod +x install.sh
23+
sudo -E ./install.sh
24+
```
25+
26+
## Enabling bash completion
27+
28+
The `devcontainer completion <shell>` command generates a completion script for the specified shell.
29+
30+
To enable bash completion, add the following to you `~/.bashrc` file:
31+
32+
```bash
33+
source <(devcontainer completion bash)
34+
```
35+
36+
Or to alias `devcontainer` (to `dc` in this example):
37+
38+
```bash
39+
alias dc=devcontainer
40+
complete -F __start_devcontainer dc
41+
```
42+
43+
The `devcontainer completion <shell>` command accepts `bash`, `zsh`, and `powershell` for the `<shell>` parameter.

‎docs/open-in-code.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# devcontainer open-in-code
2+
3+
The `devcontainer open-in-code` command opens the current folder in VS Code as a dev container, i.e. it skips the normal step of opening in VS Code and then clicking # on the "Re-open in container" prompt to reload the window as a dev container. With `devcontainer open-in-code` you get straight to the dev container!
4+
5+
You can also use `devcontainer open-in-code <path>` to open a different folder as a devcontainer.
6+
7+
If you want to use the VS Code Insiders release, you can use `devcontainer open-in-code-insiders`.

‎docs/template.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# devcontainer template ...
2+
3+
{:toc}
4+
5+
## Setting up templates
6+
7+
To use the `devcontainer template` commands you need to configure some templates.
8+
9+
A good starting point is the the VS Code devcontainers repo. Choose a directory, and clone the repo using `git clone https://github.com/microsoft/vscode-dev-containers`
10+
11+
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.
12+
13+
The starting configuration will look something like:
14+
15+
```json
16+
{
17+
"templatepaths": []
18+
}
19+
```
20+
21+
Update to include the path to the `containers` folder in the `vscode-dev-containers` repo you just cloned:
22+
23+
```json
24+
{
25+
"templatepaths": ["$HOME/source/vscode-dev-containers/containers"]
26+
}
27+
```
28+
29+
## Listing templates
30+
31+
Running `devcontainer template list` will show the templates that `devcontainer` discovered
32+
33+
## Adding a devcontainer definition
34+
35+
To add the files for a devcontainer definition to your project, change directory to the folder you want to add the devcontainer to and then run:
36+
37+
```bash
38+
# Add the go template
39+
devcontainer template add go
40+
```
41+
42+
This will copy in the template files for you to modify as you wish.
43+
44+
## Adding a link to a devcontainer
45+
46+
If you are working with a codebase that you don't want to commit the devcontainer definition to (e.g. an OSS project that doesn't want a devcontainer definition), you can use the `template add-link` command. Instead of copying template files it creates symlinks to the template files and adds a `.gitignore` file to avoid accidental git commits.
47+
48+
As with `template add`, run this from the folder you want to add the devcontainer to:
49+
50+
```bash
51+
# Symlink to the go template
52+
devcontainer template add-link go
53+
```
54+
55+
See the [repository containers](#repository-containers) section for an alternative to template links.
56+
57+
## Creating your own templates
58+
59+
`devcontainer` can be configured to scan multiple folders to find templates. It is designed to work with folders structured in the same was as the [containers from in github.com/microsoft/vscode-dev-containers](https://github.com/microsoft/vscode-dev-containers/tree/master/containers), e.g.:
60+
61+
62+
```misc
63+
template-collection-folder
64+
|-template1
65+
| |-.devcontainer
66+
| | |-devcontainer.json
67+
| | |-Dockerfile
68+
| | |-<other content for the template>
69+
|-misc-folder
70+
|-<misc content that is ignored as there is no .devcontainer folder>
71+
|-<README or other files that are ignore>
72+
```
73+
74+
Assuming you cloned [github.com/microsoft/vscode-dev-containers/](https://github.com/microsoft/vscode-dev-containers/) into your `~/source/` folder and set up a custom devcontainer folder in `~/source/devcontainers` then you can configure your template paths as shown below. The sub-folder names are used as the template name and when duplicates are found the first matching folder is taken, so in the example below the `~/source/devcontainers` templates take precedence.
75+
76+
```json
77+
{
78+
"templatepaths": [
79+
"$HOME/source/devcontainers",
80+
"$HOME/source/vscode-dev-containers/containers"
81+
]
82+
}
83+
```
84+
85+
## Repository containers
86+
87+
VS Code dev containers have another feature called "Repository containers". These are a set of dev container definitions that VS Code will automatically apply to a project based on its git repo.
88+
89+
The default definitions are in the [microsoft/vscode-dev-containers](https://github.com/microsoft/vscode-dev-containers/tree/master/repository-containers) repo. If you look at the repo, you will see a `github.com` folder followed by paths for `<org>/<repo>`, e.g. `django/django`. The `https://github.com/django/django` repo doesn't contain a dev container definition, but VS Code will use the repository container definition from the `microsoft/vscode-dev-containers` repo.
90+
91+
You can also configure VS Code to look for additional local paths for repository containers by providing a value for the VS Code `remote.containers.repository-container-paths` setting (see [this issue](https://github.com/microsoft/vscode-remote-release/issues/3218) for more details).
92+

0 commit comments

Comments
 (0)