devcontainer.vim

A tool for developing with Vim on a container. (Vim version of VSCode Dev Container)

It's a tool that adds and starts settings for Vim-based Dev Container development in the form of additions to the devcontainer.json file created for VSCode.

Getting Started

Developing with Vim on a container using devcontainer.vim (Environment construction from scratch) - mikoto2000's blog
Go programming using devcontainer.vim and codex cli! - YouTube
Java programming using devcontainer.vim and Claude Code! - YouTube
? "What! Setting up Go environment in 1 minute?!" devcontainer.vim "I can do it!" - YouTube

Features:

Set up a development container, transfer Vim/NeoVim and tmux to it, and start Vim inside tmux.
- For projects without devcontainer.json, launch a development container in a single shot
  - You can customize the arguments passed to docker.
- Add a template for devcontainer.json to projects that don't have a devcontainer.json file
- In a project with a devcontainer.json file, you can start, stop, and delete the development container.
- In addition to devcontainer.json, you can add settings for devcontainer.vim to the development container by specifying devcontainer.vim.json.
- You can define a vimrc to be used with Vim launched in a development container.
- If the path to Vim/NeoVim is set in the development container, use it.
The text copied in Vim on the development container can be pasted to the clipboard of the host PC.
Transfer tools to be used in the development container to make them usable in the development container.
Tools such as vim, devcontainer, and clipboard-data-receiver can be updated.
Self-update capability

Requirements:

The following commands are installed and in the PATH.

docker

The following commands must exist in the container and be in the PATH.

which
hostname

For ARM, the tar command must be present in the container.

Usage:

NAME:
   devcontainer.vim - devcontainer for vim.

USAGE:
   devcontainer.vim [global options] command [command options]

VERSION:
   4.0.0

COMMANDS:
   run                 Run container use `docker run`
   templates           Run `devcontainer templates`
   start               Run `devcontainer up` and `devcontainer exec`
   stop                Stop devcontainers.
   down                Stop and remove devcontainers.
   config              devcontainer.vim's config information.
   vimrc               devcontainer.vim's vimrc information.
   runargs             run subcommand's default arguments.
   tool                Management tools
   clean               clean workspace cache files.
   index               Management dev container template index file
   self-update         Update devcontainer.vim itself
   bash-complete-func  Show bash complete func
   help, h             Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --license, -l  show licensesa.
   --nvim         use NeoVim.
   --nocdr        disable clipboard-data-receiver.
   --notmux       disable tmux.
   --shell value  start with shell.
   --help, -h     show help
   --version, -v  print the version

Set up an environment in a project where `devcontainer.json` does not exist.

devcontainer.vim run [DOCKER_OPTIONS] [DOCKER_ARGS]

Example of running a container in an environment equivalent to the docker run -it --rm -v "$(pwd):/work" --workdir /work -v "${HOME}/.vim:/root/.vim" --name golang golang:1.22.1-bookworm command:

devcontainer.vim run -v "$(pwd):/work" --workdir /work -v "${HOME}/.vim:/root/.vim" --name golang golang:1.22.1-bookworm

if `devcontainer.json` exists

Environmental start

The start subcommand sets up the environment, transfers Vim, and starts it.

For example, if you want to search for devcontainer.json in the current directory, read it, set up the environment, transfer Vim, and start it, you can do the following.

devcontainer.vim start .

If you want to launch Vim/NeoVim directly without tmux, add --notmux.

devcontainer.vim --notmux start .

You can use arguments to devcontainer (except for --workspace-folder) as they are, so if you want to bind .vim, specify it as follows.

devcontainer.vim start --mount "type=bind,source=${HOME}/.vim,target=/root/.vim" .

Environmental stop

The stop subcommand allows you to stop the environment.

devcontainer.vim stop .

To resume, execute the start subcommand again.

Environment deletion

The down subcommand can delete the environment.

devcontainer.vim down .

Tool update

To update the tools used internally by devcontainer.vim, use the tool subcommand.

# update Vim
devcontainer.vim tool vim download

# update tmux
devcontainer.vim tool tmux download

# update devcontainer CLI
devcontainer.vim tool devcontainer download

self update

You can update devcontainer.vim to the latest version using the self-update subcommand.

devcontainer.vim self-update

Create `devcontainer.json` based on the template

The devcontainer.vim templates apply subcommand allows you to generate a devcontainer.json file from templates provided by devcontainers.

Example of generating devcontainer.json using the Go template:

$ devcontainer.vim templates apply .
Search: Go
? Select Template:
  ▸ Go
    Go & PostgreSQL
    Node.js & Mongo DB
    Hugo & pnpm

Running devcontainer.vim templates apply will show a list of template names. You can use the key input to incrementally search for names, move the cursor with the up and down keys, and select a template with the Enter key.

Subcommand Completion

Passing the path to devcontainer.vim and adding the following code to .bashrc or similar will enable subcommand completion.

eval "$(devcontainer.vim bash-complete-func)"

Customize:

Container Customization

I want to bind some things like .vim and vimfiles from the host to the bind mount, but I don't want to add a mounts definition specific to devcontainer.vim to the devcontainer.json that I created for other tools like VSCode.

Therefore, the file that is read only by devcontainer.vim is placed in .devcontainer/devcontainer.vim.json. devcontainer.vim merges and executes .devcontainer/devcontainer.json and .devcontainer/devcontainer.vim.json.

PROJECT_ROOT/
    +- .devcontainer/
    |   +- devcontainer.json      # Ordinary settings for devcontainer
    |   +- devcontainer.vim.json  # Settings used only by devcontainer.vim, such as mounting .vim
    |
    +- ...(other project files)

devcontainer.json:

{
  "name":"Go",
  "image":"mcr.microsoft.com/devcontainers/go:1-1.22-bookworm",
  "features":{},
  "remoteUser":"vscode"
}

devcontainer.vim.json:

{
  "mounts": [
    {
      "type": "dereferenced",
      "source": "${localEnv:HOME}/.vim",
      "target": "/home/vscode/.vim"
    }
  ]
}

The "type": "dereferenced" mount type is a special feature of devcontainer.vim.json. Unlike a standard docker "bind" mount, a "dereferenced" mount copies the file or directory from the host to the container while resolving any symlinks on the host side. This is especially useful for directories like ~/.vim and ~/.claude which are often heavily symlinked on host machines.

Generate additional settings

devcontainer.vim config -g generates a template for additional configuration files used by devcontainer.vim.

devcontainer.vim config -g --home /home/containerUser > .devcontainer/devcontainer.vim.json

Available options are as follows:

-g : setting generation flag
-o : Specify the output file for the generated configuration (default: STDOUT)
--home: Path to the home directory in the configuration template

Install additional runtime in the container

If you use plugins that require a separate runtime, such as denops.vim or coc.nvim, you can install the runtime in the container by adding the image ID to the features section of devcontainer.vim.json.

Example of installing deno in a container:

...(snip)
  "features": {
    "ghcr.io/devcontainers-community/features/deno:1": {}
  }
...(snip)

The images that can be specified in features can be checked in Available Dev Container Features.

Vim Customization

Creating a vimrc that is only loaded for Vim on devcontainer.vim

devcontainer.vim vimrc -o opens a script that will be additionally loaded into Vim running in the container.

Updating this script allows you to apply settings only to Vim on the container.

The default behavior sends the contents of the " register to the host using "*yy in normal mode and "*y in visual mode. Adjust as desired.

The default is as follows:

if !has("nvim")
  nnoremap <silent> "*yy yy:call SendToCdr('"')<CR>
  vnoremap <silent> "*y y:call SendToCdr('"')<CR>
else
  nnoremap <silent> "*yy yy:lua SendToCdr('"')<CR>
  vnoremap <silent> "*y y:lua SendToCdr('"')<CR>
endif

To revert to the default, regenerate vimrc with the -g option.

devcontainer.vim vimrc -g

Vim script that should only be executed in Vim on devcontainer.vim

When Vim runs on devcontainer.vim, the g:devcontainer_vim variable is defined as v:true.

By checking this variable, you can write Vim scripts that run only on Vim in devcontainer.vim.

if get(g:, "devcontainer_vim", v:false)
  " Run only on devcontainer.vim
endif

Customize the arguments of `run` subcommand

devcontainer.vim runargs -o opens the argument settings file that is implicitly set to the run subcommand.

Updating this file allows you to specify arguments that you want to apply implicitly.

By default, it mounts the current directory to /work and sets the working directory to the same location. Adjust as desired.

The default is as follows:

-v "$(pwd):/work" -v "${HOME}/.vim:/root/.vim" --workdir /work

To revert to the default, regenerate runargs with the -g option.

devcontainer.vim runargs -g

Using NeoVim

By adding the --nvim option or setting the environment variable DEVCONTAINER_VIM_TYPE to nvim, the nvim AppImage will be transferred and launched instead of vim.

devcontainer.vim --nvim start .

or

export DEVCONTAINER_VIM_TYPE=nvim
devcontainer.vim start .

Using Shell

By adding the --shell option or setting the environment variable DEVCONTAINER_SHELL_TYPE to a shell name, the shell will be launched instead of vim.

devcontainer.vim --shell bash start .

or

export DEVCONTAINER_SHELL_TYPE=bash
devcontainer.vim start .

If you want to use the transferred Vim/Neovim inside tmux, run /run_vim.sh.

Limitation:

amd64 architecture cannot be used in alpine-based containers
When using NeoVim in an aarch64 container, you must use the system-installed version
If the NeoVim AppImage is not available and there is no system-installed NeoVim, Vim will start instead of NeoVim
When using NeoVim on macOS, only the system-installed NeoVim can be used If the system-installed NeoVim cannot be detected, Vim will start instead
Clipboard integration doesn't work when using docker on WSL2
If you are using WSL2 Integration with Docker Desktop, forwardPorts may not work properly, so please use appPort instead.

Install:

binary download

Latest version

go install

go install github.com/mikoto2000/devcontainer.vim/v3@latest

If you want to install by specifying the version, install with the following command.

Due to an incomplete setting, only v3.0.2 or later can be installed by specifying the version.

go install github.com/mikoto2000/devcontainer.vim/v3@3.0.2

Uninstall:

Windows

Delete executable file, config directory(~/AppData/Roaming/devcontainer.vim), and cache directory(~/AppData/Local/devcontainer.vim).

Remove-Item PATH_TO/devcontainer.vim.exe
Remove-Item -Recurse ~/AppData/Roaming/devcontainer.vim
Remove-Item -Recurse ~/AppData/Local/devcontainer.vim

Linux

Delete executable file, config directory(~/.config/devcontainer.vim), and cache directory(~/.cache/devcontainer.vim).

rm PATH_TO/devcontainer.vim
rm -rf ~/.config/devcontainer.vim
rm -rf ~/.cache/devcontainer.vim

MacOS

rm PATH_TO/devcontainer.vim
rm -rf ~/Library/Application Support/devcontainer.vim
rm -rf ~/Library/Caches/devcontainer.vim

License:

This software is released under the MIT License, see LICENSE

This software is published under the MIT License. See LICENSE.

Author:

mikoto2000 mikoto2000@gmail.com Antonia Stevens a@ant.st

Name		Name	Last commit message	Last commit date
Latest commit History 452 Commits
.devcontainer		.devcontainer
.github/workflows		.github/workflows
devcontainer		devcontainer
docker		docker
dockercompose		dockercompose
oras		oras
test		test
tools		tools
util		util
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
Makefile		Makefile
NOTICE		NOTICE
README.md		README.md
bash_complete_func.bash		bash_complete_func.bash
devcontainer.vim.template.json		devcontainer.vim.template.json
go.mod		go.mod
go.sum		go.sum
main.go		main.go
main_test.go		main_test.go
vimrc.template.vim		vimrc.template.vim

Folders and files

Latest commit

History

Repository files navigation