Skip to content

README.md

Latest commit

 

History

History
441 lines (295 loc) · 9.63 KB

README.md

File metadata and controls

441 lines (295 loc) · 9.63 KB

dev-code

     _                                _
    | |                              | |
  __| | _____   ________ ___ ___   __| | ___
 / _` |/ _ \ \ / /______/ __/ _ \ / _` |/ _ \
| (_| |  __/\ V /      | (_| (_) | (_| |  __/
 \__,_|\___| \_/        \___\___/ \__,_|\___|
  project · editor · container — simplified

GitHub Coverage PyPI version Python 3.10+ License: MIT

Reusable Dev Containers for any project — without modifying the repository.

Table of Contents

Background

devcode is a CLI that opens any project in VS Code Dev Containers using reusable, local templates.

Define your environment once and reuse it across projects.

Typical Dev Container workflows involve:

  • Copying .devcontainer/ directories between projects
  • Recreating environments repeatedly
  • Committing configuration to repositories you do not control

devcode separates environment configuration from project code:

  • Templates are stored locally
  • Projects remain unchanged
  • Containers are launched with a single command

Install

Dependencies

pip install dev-code

Usage

# Open a project (auto-detects template from container history, or uses default)
devcode open ~/projects/my-app

# Open with an explicit template
devcode open ~/projects/my-app dev-code

Typical Workflow

devcode template new python-dev
devcode template edit python-dev
devcode open ~/projects/my-app python-dev

Project Switching

devcode list -a -i

Lists containers and allows reopening projects interactively.

Advanced Options

  • Multiple template directories
  • Verbose debugging (-v)
  • Dry runs (--dry-run)
  • Custom container paths

Internal Flow

  1. Validate project path (must exist)
  2. Resolve template (explicit → container history → settings default)
  3. Launch VS Code Dev Container
  4. Apply file injection rules

Configuration

devcode reads settings.json from:

~/.config/dev-code/settings.json

Override the config directory:

DEVCODE_CONF_DIR=/custom/path devcode open ~/projects/my-app

The file is created automatically with defaults on first run.

settings.json

{
  "template_sources": ["~/.local/share/dev-code/templates"],
  "default_template": "dev-code",
  "template_write_dir": null
}
Key Description
template_sources Ordered list of template directories searched when resolving templates.
default_template Template used when devcode open is called without a template argument and no container history is found. Error if unset.
template_write_dir Directory where devcode template new writes new templates. null (default) uses the XDG data home: ~/.local/share/dev-code/templates. Overridden per-invocation by --path.

Template System

Default Location

~/.local/share/dev-code/templates/

Configure additional paths via template_sources in settings.json (see Configuration).

File Injection

Inject files from the host into the container at startup.

Example

{
  "customizations": {
    "dev-code": {
      "cp": [
        {
          "source": "${localEnv:HOME}/.config/myapp",
          "target": "/home/vscode/.config/myapp"
        }
      ]
    }
  }
}

Fields

Field Required Description
source Yes Host path
target Yes Container path
override No Skip if target exists (default: false)
owner No Requires group
group No Requires owner
permissions No chmod applied recursively

Source Behavior

  • Supports ${localEnv:VAR}
  • Supports relative paths from .devcontainer/
  • Missing environment variables cause the entry to be skipped

Copy Directory Contents

Use /. suffix:

{
  "source": "${localEnv:HOME}/.config/myapp/.",
  "target": "/home/vscode/.config/myapp/"
}

Copies directory contents instead of the directory itself.

Behavior Rules

  • target/ copies into the directory
  • Without trailing / copies as a file or directory
  • override=false skips existing files
  • Ownership and permissions are applied after copying

API

Full reference for all devcode commands and flags.

Global Flags

-v, --verbose   Enable debug output
--version       Show version and exit

devcode open

devcode open <path> [template] [options]

Open a project in VS Code using a devcontainer template.

Arguments

  • <path> — Project directory (must exist)
  • [template] (optional) — Template name, path to a devcontainer.json, or path to a directory containing it. Paths must start with ./, ../, /, or ~/. If omitted, devcode resolves in this order:
    1. Most recently running container for this project path
    2. Most recently stopped container for this project path
    3. default_template from settings.json (error if not set)

Options

Option Default Description
--dry-run — Print resolved configuration and actions without executing
--container-folder <path> resolved from devcontainer config Container mount path
--timeout <seconds> 300 Time to wait for container startup

devcode list

devcode list [-a] [-i]

List dev containers.

Flag Description
-a, --all Include stopped containers
-i, --interactive Prompt to reopen a listed container

Interactive mode prompts Open [1-N]: — selecting a number reopens the project in VS Code.

devcode prune

devcode prune [path] [options]

Remove stopped dev containers. Either [path] or --all-projects is required.

Arguments

  • [path] (optional) — Limit pruning to containers for this project directory.

Options

Option Description
--all-projects Prune stopped containers across all projects
--include-recent Also prune the most recently used container (skipped by default)

devcode template

devcode template <subcommand>

Manage dev container templates.

devcode template new

devcode template new <name> [base] [options]

Create a new template by copying a base template.

Argument Default Description
[base] dev-code Template to copy from
Option Description
--edit Launch the new template as a Dev Container in VS Code after creation
--path <dir> Write the new template into <dir> instead of the configured write target

devcode template edit

devcode template edit <template>

Open a template directory in VS Code for editing.

devcode template list

devcode template list [--long]

List available templates.

Option Description
--long Show description and full path for each template

devcode template default

devcode template default [name]

Get or set the default template.

  • Without name: prints the current default.
  • With name: sets default_template in settings.json.

devcode template source

devcode template source <subcommand>

Manage template search paths stored in settings.json.

devcode template source list

devcode template source list

Print all configured template search paths, one per line.

devcode template source add

devcode template source add <path>

Append <path> to template_sources in settings.json. Prints a notice and exits cleanly if already present.

devcode template source remove

devcode template source remove <path>

Remove <path> from template_sources in settings.json. Exits with an error if not found.

devcode completion

devcode completion bash
devcode completion zsh
devcode completion fish

Print the shell completion setup command for the given shell.

Add to your shell rc file for persistent completion:

# bash (~/.bashrc)
eval "$(devcode completion bash)"

# zsh (~/.zshrc)
eval "$(devcode completion zsh)"

# fish (~/.config/fish/config.fish)
eval (devcode completion fish)

Contributing

Ask questions, report bugs, or request features in Issues.

PRs welcome. Open an issue first for significant changes.

Run tox (or pytest for a single-interpreter run) before submitting.

License

MIT © Nasser Alansari (dacrystal)

See LICENSE.