devcontainer.txt

*devcontainer.txt* Description

INTRODUCTION                                     *devcontainer-main*

Description

CONTENTS                                         *devcontainer-contents*

  1.  Overview                                   |devcontainer-overview|
  2.  Requirements                               |devcontainer-requirements|
  3.  Installation                               |devcontainer-installation|
  4.  Usage                                      |devcontainer-usage|
  5.  Commands                                   |devcontainer-commands|
  6.  Functions                                  |devcontainer-functions|
  7.  Events                                     |devcontainer-autocmd-events|
  8.  Issues                                     |devcontainer-issues|
  9.  Contributing                               |devcontainer-contributing|
  10. Version                                    |devcontainer-version|
  11. License                                    |devcontainer-license|

OVERVIEW                                         *devcontainer-overview*

REQUIREMENTS                                     *devcontainer-requirements*

INSTALLATION                                     *devcontainer-installation*

1. lazy.nvim <https://github.com/folke/lazy.nvim>

Add the following to your lazy setup: >

  'https://codeberg.org/esensar/nvim-dev-container'
<

2. Plug <https://github.com/junegunn/vim-plug>

Add the following to your vimrc, or something sourced therein: >

  Plug 'https://codeberg.org/esensar/nvim-dev-container'
<
Then install via `:PlugInstall`

3. Manual

Clone this repository and copy the files in plugin/, lua/, and doc/
to their respective directories in your vimfiles, or copy the text from
the repository into new files in those directories. Make sure to
run `:helptags`.

USAGE                                            *devcontainer-usage*

To use the plugin with defaults just call the `setup` function: >

  require("devcontainer").setup{}
<

It is possible to override some of the functionality of the plugin with options passed into `setup`. Everything passed to `setup` is optional. Following block represents default values: >

  require("devcontainer").setup {
    config_search_start = function()
      -- By default this function uses vim.loop.cwd()
      -- This is used to find a starting point for .devcontainer.json file search
      -- Since by default, it is searched for recursively
      -- That behavior can also be disabled
    end,
    workspace_folder_provider = function()
      -- By default this function uses first workspace folder for integrated lsp if available and vim.loop.cwd() as a fallback
      -- This is used to replace `${localWorkspaceFolder}` in devcontainer.json
      -- Also used for creating default .devcontainer.json file
    end,
    terminal_handler = function(command)
      -- By default this function creates a terminal in a new tab using :terminal command
      -- It also removes statusline when that tab is active, to prevent double statusline
      -- It can be overridden to provide custom terminal handling
    end,
    nvim_installation_commands_provider = function(path_binaries, version_string)
      -- Returns table - list of commands to run when adding neovim to container
      -- Each command can either be a string or a table (list of command parts)
      -- Takes binaries available in path on current container and version_string passed to the command or current version of neovim
    end,
    devcontainer_json_template = function()
      -- Returns table - list of lines to set when creating new devcontainer.json files
      -- As a template
      -- Used only when using functions from commands module or created commands
    end,
    -- Can be set to false to prevent generating default commands
    -- Default commands are listed below
    generate_commands = true,
    -- By default no autocommands are generated
    -- This option can be used to configure automatic starting and cleaning of containers
    autocommands = {
      -- can be set to true (or "ask") to automatically start containers when devcontainer.json is available - if set to "ask", it will prompt before starting
      init = false,
      -- can be set to true to automatically remove any started containers and any built images when exiting vim
      clean = false,
      -- can be set to true to automatically restart containers when devcontainer.json file is updated
      update = false,
    },
    -- can be changed to increase or decrease logging from library
    log_level = "info",
    -- can be set to true to disable recursive search
    -- in that case only .devcontainer.json and .devcontainer/devcontainer.json files will be checked relative
    -- to the directory provided by config_search_start
    disable_recursive_config_search = false,
    -- can be set to false to disable image caching when adding neovim
    -- by default it is set to true to make attaching to containers faster after first time
    cache_images = true,
    -- By default all mounts are added (config, data and state)
    -- This can be changed to disable mounts or change their options
    -- This can be useful to mount local configuration
    -- And any other mounts when attaching to containers with this plugin
    attach_mounts = {
      neovim_config = {
        -- enables mounting local config to /root/.config/nvim in container
        enabled = false,
        -- makes mount readonly in container
        options = { "readonly" }
      },
      neovim_data = {
        -- enables mounting local data to /root/.local/share/nvim in container
        enabled = false,
        -- no options by default
        options = {}
      },
      -- Only useful if using neovim 0.8.0+
      neovim_state = {
        -- enables mounting local state to /root/.local/state/nvim in container
        enabled = false,
        -- no options by default
        options = {}
      },
    },
    -- This takes a list of mounts (strings or tables) that should always be added to every run container
    -- This is passed directly as --mount option to docker command
    -- Or multiple --mount options if there are multiple vaues
    always_mount = {}
    -- This takes a string (usually either "podman" or "docker") representing container runtime - "devcontainer-cli" is also partially supported
    -- That is the command that will be invoked for container operations
    -- If it is nil, plugin will use whatever is available (trying "podman" first)
    container_runtime = nil,
    -- Similar to container runtime, but will be used if main runtime does not support an action - useful for "devcontainer-cli"
    backup_runtime = nil,
    -- This takes a string (usually either "podman-compose" or "docker-compose") representing compose command - "devcontainer-cli" is also partially supported
    -- That is the command that will be invoked for compose operations
    -- If it is nil, plugin will use whatever is available (trying "podman-compose" first)
    compose_command = nil,
    -- Similar to compose command, but will be used if main command does not support an action - useful for "devcontainer-cli"
    backup_compose_command = nil,
  }
<

Check out [wiki](https://codeberg.org/esensar/nvim-dev-container/wiki) for tips.

COMMANDS                                         *devcontainer-commands*

If not disabled by using {generate_commands = false} in setup, this plugin provides the following commands:

*:DevcontainerStart* - start whatever is defined in devcontainer.json
*:DevcontainerAttach* - attach to whatever is defined in devcontainer.json
*:DevcontainerExec* - execute a single command on container defined in devcontainer.json
*:DevcontainerStop* - stop whatever was started based on devcontainer.json
*:DevcontainerStopAll* - stop everything started with this plugin (in current session)
*:DevcontainerRemoveAll* - remove everything started with this plugin (in current session)
*:DevcontainerLogs* - open plugin log file
*:DevcontainerEditNearestConfig* - opens nearest devcontainer.json file if it exists, or creates a new one if it does not

FUNCTIONS                                        *devcontainer-functions*

This plugin provides multiple modules related to devcontainer functionality,
but not all of them are needed for use tasks. Many of the functionalities are
exposed to enable custom functionality.

==============================================================================
High level devcontainer commands                         *devcontainer.commands*

Provides functions representing high level devcontainer commands

M.compose_up({callback?})                     *devcontainer.commands.compose_up*
    Run docker-compose up from nearest devcontainer.json file

    Parameters: ~
        {callback?}  (function)  called on success - parsed devcontainer config is passed to the callback

    Usage: ~
>lua
        require("devcontainer.commands").compose_up()
<


M.compose_down({callback?})                 *devcontainer.commands.compose_down*
    Run docker-compose down from nearest devcontainer.json file

    Parameters: ~
        {callback?}  (function)  called on success - parsed devcontainer config is passed to the callback

    Usage: ~
>lua
        require("devcontainer.commands").compose_down()
<


M.compose_rm({callback?})                     *devcontainer.commands.compose_rm*
    Run docker-compose rm from nearest devcontainer.json file

    Parameters: ~
        {callback?}  (function)  called on success - parsed devcontainer config is passed to the callback

    Usage: ~
>lua
        require("devcontainer.commands").compose_rm()
<


M.docker_build({callback?})                 *devcontainer.commands.docker_build*
    Run docker build from nearest devcontainer.json file

    Parameters: ~
        {callback?}  (function)  called on success - parsed devcontainer config and image id are passed to the callback

    Usage: ~
>lua
        require("devcontainer.commands").docker_build()
<


M.docker_image_run({callback?})         *devcontainer.commands.docker_image_run*
    Run docker run from nearest devcontainer.json file

    Parameters: ~
        {callback?}  (function)  called on success - devcontainer config and container id are passed to the callback

    Usage: ~
>lua
        require("devcontainer.commands").docker_image_run()
<


                                    *devcontainer.commands.docker_build_and_run*
M.docker_build_and_run({callback?})
    Run docker run from nearest devcontainer.json file, building before that

    Parameters: ~
        {callback?}  (function)  called on success - devcontainer config and container id are passed to the callback

    Usage: ~
>lua
        require("devcontainer.commands").docker_build_and_run()
<


                             *devcontainer.commands.docker_build_run_and_attach*
M.docker_build_run_and_attach({callback?})
    Run docker run from nearest devcontainer.json file, building before that
    And then attach to the container with neovim added

    Parameters: ~
        {callback?}  (function)  called on success - devcontainer config and container id are passed to the callback

    Usage: ~
>lua
        require("devcontainer.commands").docker_build_run_and_attach()
<


M.start_auto({callback?}, {attach?})          *devcontainer.commands.start_auto*
    Parses devcontainer.json and starts whatever is defined there
    Looks for dockerComposeFile first
    Then it looks for dockerfile
    And last it looks for image

    Parameters: ~
        {callback?}  (function)  called on success - devcontainer config is passed to the callback
        {attach?}    (boolean)   if true, automatically attach after starting

    Usage: ~
>lua
        require("devcontainer.commands").start_auto()
<


                                             *devcontainer.commands.attach_auto*
M.attach_auto({target}, {command}, {callback?})
    Parses devcontainer.json and attaches to whatever is defined there
    Looks for dockerComposeFile first
    Then it looks for dockerfile
    And last it looks for image

    Parameters: ~
        {target}     (string)        container id, or latest or devcontainer
        {command}    (string|table)  command to run on container
        {callback?}  (function)      called on success - devcontainer config is passed to the callback

    Usage: ~
>lua
        require("devcontainer.commands").attach_auto()
<


M.exec({target}, {command}, {callback?})            *devcontainer.commands.exec*
    Parses devcontainer.json and stops whatever is defined there
    Looks for dockerComposeFile first
    Then it looks for dockerfile
    And last it looks for image

    Parameters: ~
        {target}     (string)        container id, or latest or devcontainer
        {command}    (string|table)  command to run on container
        {callback?}  (function)      called on success - devcontainer config is passed to the callback

    Usage: ~
>lua
        require("devcontainer.commands").exec("devcontainer", "ls", { on_success = function(result) end })
<


M.stop_auto({callback?})                       *devcontainer.commands.stop_auto*
    Parses devcontainer.json and stops whatever is defined there
    Looks for dockerComposeFile first
    Then it looks for dockerfile
    And last it looks for image

    Parameters: ~
        {callback?}  (function)  called on success - devcontainer config is passed to the callback

    Usage: ~
>lua
        require("devcontainer.commands").stop_auto()
<


M.stop_all({callback?})                         *devcontainer.commands.stop_all*
    Stops everything started with devcontainer plugin

    Parameters: ~
        {callback?}  (function)  called on success

    Usage: ~
>lua
        require("devcontainer.commands").stop_all()
<


M.remove_all({callback?})                     *devcontainer.commands.remove_all*
    Removes everything started with devcontainer plugin

    Parameters: ~
        {callback?}  (function)  called on success

    Usage: ~
>lua
        require("devcontainer.commands").remove_all()
<


M.open_logs()                                  *devcontainer.commands.open_logs*
    Opens log file in a new buffer

    Usage: ~
>lua
        require("devcontainer.commands").open_logs()
<


                        *devcontainer.commands.open_nearest_devcontainer_config*
M.open_nearest_devcontainer_config()
    Opens nearest devcontainer config in a new buffer

    Usage: ~
>lua
        require("devcontainer.commands").open_nearest_devcontainer_config()
<


                                *devcontainer.commands.edit_devcontainer_config*
M.edit_devcontainer_config()
    Opens nearest devcontainer config in a new buffer or creates a new one in .devcontainer/devcontainer.json

    Usage: ~
>lua
        require("devcontainer.commands").edit_devcontainer_config()
<


==============================================================================
Compose module                                            *devcontainer.compose*

Provides functions related to compose control

ComposeUpOpts                               *devcontainer.compose.ComposeUpOpts*

    Fields: ~
        {args?}       (table)     list of additional arguments to up command
        {on_success}  (function)


M.up({compose_file}, {opts})                           *devcontainer.compose.up*
    Run docker-compose up with passed file

    Parameters: ~
        {compose_file}  (string|table)   path to docker-compose.yml file or files
        {opts}          (ComposeUpOpts)  Additional options including callbacks

    Usage: ~
>lua
        require("devcontainer.compose").up("docker-compose.yml")
<


ComposeDownOpts                           *devcontainer.compose.ComposeDownOpts*

    Fields: ~
        {on_success}  (function)


M.down({compose_file}, {opts})                       *devcontainer.compose.down*
    Run docker-compose down with passed file

    Parameters: ~
        {compose_file}  (string|table)     path to docker-compose.yml file or files
        {opts}          (ComposeDownOpts)  Additional options including callbacks

    Usage: ~
>lua
        require("devcontainer.compose").down("docker-compose.yml")
<


                                *devcontainer.compose.ComposeGetContainerIdOpts*
ComposeGetContainerIdOpts

    Fields: ~
        {on_success?}  (function)


                                         *devcontainer.compose.get_container_id*
M.get_container_id({compose_file}, {service}, {opts})
    Run docker-compose ps with passed file and service to get its container_id

    Parameters: ~
        {compose_file}  (string|table)               path to docker-compose.yml file or files
        {service}       (string)                     service name
        {opts}          (ComposeGetContainerIdOpts)  Additional options including callbacks

    Usage: ~
>lua
        require("devcontainer.compose").get_container_id(
          "docker-compose.yml",
          { on_success = function(container_id) end }
        )
<


==============================================================================
Jsonc parsing module                            *devcontainer.config_file.jsonc*

Vim supports Json parsing by default, but devcontainer config files are Jsonc.
This module supports Jsonc parsing by removing comments and then parsing as Json.
Treesitter is used for this and json parser needs to be installed.

                                    *devcontainer.config_file.jsonc.parse_jsonc*
M.parse_jsonc({jsonc_content})
    Parse Json string into a Lua table
    Usually file should be read and content should be passed as a string into the function

    Parameters: ~
        {jsonc_content}  (string)  @return table?

    Usage: ~
>lua
        require("devcontainer.config_file.jsonc").parse_jsonc([[{ "test": "value" }]])
<


==============================================================================
Devcontainer config file parsing module         *devcontainer.config_file.parse*

Provides support for parsing specific devcontainer.json files as well as
automatic discovery and parsing of nearest file
Ensures basic configuration required for the plugin to work is present in files

                      *devcontainer.config_file.parse.parse_devcontainer_config*
M.parse_devcontainer_config({config_file_path}, {callback?})
    Parse specific devcontainer.json file into a Lua table
    Ensures that at least one of "image", "dockerFile" or "dockerComposeFile" keys is present

    Parameters: ~
        {config_file_path}  (string)
        {callback?}         (function)  if nil run sync, otherwise run async and pass result to the callback(err, data)
                                        @return table? result or nil if running async

    Usage: ~
>lua
        require("devcontainer.config_file.parse").parse_devcontainer_config([[{ "image": "test" }]])
<


              *devcontainer.config_file.parse.parse_nearest_devcontainer_config*
M.parse_nearest_devcontainer_config({callback?})
    Parse nearest devcontainer.json file into a Lua table
    Prefers .devcontainer.json over .devcontainer/devcontainer.json
    Looks in config.config_search_start first and then moves up all the way until root
    Fails if no devcontainer.json files were found, or if the first one found is invalid

    Parameters: ~
        {callback?}  (function)  if nil run sync, otherwise run async and pass result to the callback(err, data)
                                 @return table? result or nil if running async

    Usage: ~
>lua
        require("devcontainer.config_file.parse").parse_nearest_devcontainer_config()
<


                                  *devcontainer.config_file.parse.fill_defaults*
M.fill_defaults({config_file})
    Fills passed devcontainer config with defaults based on spec
    Expects a proper config file, parsed with functions from this module
    NOTE: This mutates passed config!

    Parameters: ~
        {config_file}  (table)  parsed config

    Returns: ~
        (table)  with filled defaults and absolute paths


                          *devcontainer.config_file.parse.remote_env_needs_fill*
M.remote_env_needs_fill({remote_env})
    Checks if remoteEnv property needs env values to be filled
    This can be used to prevent making needless calls to the container

    Parameters: ~
        {remote_env}  (table)  remoteEnv property of parsed config

    Returns: ~
        (boolean)  if environment is required to fill out remoteEnv


                                *devcontainer.config_file.parse.fill_remote_env*
M.fill_remote_env({remote_env}, {env_map})
    Fill passed remoteEnv table with values from env_map
    Env_map should usually be generated from environment of the running container
    NOTE: This mutates passed remoteEnv!

    Parameters: ~
        {remote_env}  (table)  remoteEnv property of parsed config
        {env_map}     (table)  map of container environment

    Returns: ~
        (table)  with replaced containerEnv values


          *devcontainer.config_file.parse.container_workspace_folder_needs_fill*
M.container_workspace_folder_needs_fill({config_table})
    Checks if configuration needs to have ${containerWorkspaceFolder}
    and ${containerWorkspaceFolderBasename} values filled in
    This can be used to prevent making needless calls to the container

    Parameters: ~
        {config_table}  (table)  parsed config

    Returns: ~
        (boolean)  if environment is required to fill out remoteEnv


                *devcontainer.config_file.parse.fill_container_workspace_folder*
M.fill_container_workspace_folder({config_table}, {container_workspace_folder})
    Checks if configuration needs to have ${containerWorkspaceFolder}
    and ${containerWorkspaceFolderBasename} values filled in
    This can be used to prevent making needless calls to the container

    Parameters: ~
        {config_table}                (table)   parsed config
        {container_workspace_folder}  (string)  workspace folder fetched from container

    Returns: ~
        (table)  with filled in containerWorkspaceFolder


               *devcontainer.config_file.parse.find_nearest_devcontainer_config*
M.find_nearest_devcontainer_config({callback?})
    Return path of the nearest devcontainer.json file
    Prefers .devcontainer.json over .devcontainer/devcontainer.json
    Looks in config.config_search_start first and then moves up all the way until root
    Fails if no devcontainer.json files were found, or if the first one found is invalid

    Parameters: ~
        {callback?}  (function)  if nil run sync, otherwise run async and pass result to the callback(err, data)
                                 @return string? result or nil if running async

    Usage: ~
>lua
        require("devcontainer.config_file.parse").find_nearest_devcontainer_config()
<


==============================================================================
Devcontainer plugin config module                          *devcontainer.config*

Provides current devcontainer plugin configuration
Don't change directly, use `devcontainer.setup{}` instead
Can be used for read-only access

M.terminal_handler                        *devcontainer.config.terminal_handler*
    Handles terminal requests (mainly used for attaching to container)
    By default it uses terminal command

    Type: ~
        (function)


                                 *devcontainer.config.workspace_folder_provider*
M.workspace_folder_provider
    Provides docker build path
    By default uses first LSP workplace folder or vim.loop.cwd()

    Type: ~
        (function)


M.config_search_start                  *devcontainer.config.config_search_start*
    Provides starting search path for .devcontainer.json
    After this search moves up until root
    By default it uses vim.loop.cwd()

    Type: ~
        (function)


                           *devcontainer.config.disable_recursive_config_search*
M.disable_recursive_config_search
    Flag to disable recursive search for .devcontainer config files
    By default plugin will move up to root looking for .devcontainer files
    This flag can be used to prevent it and only look in M.config_search_start

    Type: ~
        (boolean)


M.cache_images                                *devcontainer.config.cache_images*
    Flag to enable image caching after adding neovim - to make further attaching faster
    True by default

    Type: ~
        (boolean)


                       *devcontainer.config.nvim_installation_commands_provider*
M.nvim_installation_commands_provider
    Provides commands for adding neovim to container
    This function should return a table listing commands to run - each command should eitehr be a table or a string
    It takes a list of executables available in the container, to decide
    which package manager to use and also version string with current neovim version

    Type: ~
        (function)


M.nvim_install_as_root                *devcontainer.config.nvim_install_as_root*
    Can be set to true to install neovim as root
    This is usually not required,
    but if default container user can't run commands defined in M.nvim_installation_commands_provider this is required

    Type: ~
        (boolean)


                                *devcontainer.config.devcontainer_json_template*
M.devcontainer_json_template
    Provides template for creating new .devcontainer.json files
    This function should return a table listing lines of the file

    Type: ~
        (function)


MountOpts                                        *devcontainer.config.MountOpts*

    Fields: ~
        {enabled}  (boolean)  if true this mount is enabled
        {options}  (table)


AttachMountsOpts                          *devcontainer.config.AttachMountsOpts*

    Fields: ~
        {neovim_config?}  (MountOpts)  if true attaches neovim local config to /root/.config/nvim in container
        {neovim_data?}    (MountOpts)  if true attaches neovim data to /root/.local/share/nvim in container
        {neovim_state?}   (MountOpts)  if true attaches neovim state to /root/.local/state/nvim in container


M.attach_mounts                              *devcontainer.config.attach_mounts*
    Configuration for mounts when using attach command
    NOTE: when attaching in a separate command, it is useful to set
    always to true, since these have to be attached when starting
    Useful to mount neovim configuration into container
    Applicable only to `devcontainer.commands` functions!

    Type: ~
        (AttachMountsOpts)


LogLevel                                          *devcontainer.config.LogLevel*

    Variants: ~
        ("trace")
        ("debug")
        ("info")
        ("warn")
        ("error")
        ("fatal")


M.log_level                                      *devcontainer.config.log_level*
    Current log level

    Type: ~
        (LogLevel)


==============================================================================
Container module                                        *devcontainer.container*

Provides functions related to container control:
 - building
 - attaching
 - running

ContainerPullOpts                     *devcontainer.container.ContainerPullOpts*

    Fields: ~
        {on_success}  (function)


M.pull({image}, {opts})                            *devcontainer.container.pull*
    Pull passed image using docker pull

    Parameters: ~
        {image}  (string)             Docker image to pull
        {opts}   (ContainerPullOpts)  Additional options including callbacks

    Usage: ~
>lua
        require("devcontainer.container").pull("alpine", { on_success = function() end, on_fail = function() end})
<


                                     *devcontainer.container.ContainerBuildOpts*
ContainerBuildOpts

    Fields: ~
        {tag?}        (string)    tag for the image built
        {args?}       (table)     list of additional arguments to build command
        {on_success}  (function)


M.build({file}, {path?}, {opts})                  *devcontainer.container.build*
    Build image from passed dockerfile using docker build

    Parameters: ~
        {file}   (string)              Path to Dockerfile to build
        {path?}  (string)              Path to the workspace, vim.lsp.buf.list_workspace_folders()[1] by default
        {opts}   (ContainerBuildOpts)  Additional options including callbacks and tag

    Usage: ~
>lua
        require("devcontainer.container").build(
          "Dockerfile",
          { on_success = function(image_id) end, on_fail = function() end }
        )
<


ContainerRunOpts                       *devcontainer.container.ContainerRunOpts*

    Fields: ~
        {autoremove?}  (boolean)           automatically remove container after stopping - false by default
        {command}      (string|table|nil)  command to run in container
        {args?}        (table)             list of additional arguments to run command
        {on_success}   (function)


M.run({image}, {opts})                              *devcontainer.container.run*
    Run passed image using docker run
    NOTE: If terminal_handler is passed, then it needs to start the process too - default termopen does just that

    Parameters: ~
        {image}  (string)            Docker image to run
        {opts}   (ContainerRunOpts)  Additional options including callbacks

    Usage: ~
>lua
        require("devcontainer.container").run("alpine", { on_success = function(id) end, on_fail = function() end })
<


ContainerExecOpts                     *devcontainer.container.ContainerExecOpts*

    Fields: ~
        {tty?}               (boolean)           attach to container TTY and display it in terminal buffer, using configured terminal handler
        {terminal_handler?}  (function)          override to open terminal in a different way, :tabnew + termopen by default
        {capture_output?}    (boolean)           if true captures output and passes it to success callback - incompatible with tty
        {command}            (string|table|nil)  command to run in container
        {args?}              (table)             list of additional arguments to exec command
        {on_success?}        (function)


M.exec({container_id}, {opts})                     *devcontainer.container.exec*
    Run command on a container using docker exec
    Useful for attaching to neovim
    NOTE: If terminal_handler is passed, then it needs to start the process too - default termopen does just that

    Parameters: ~
        {container_id}  (string)             Docker container to exec on
        {opts}          (ContainerExecOpts)  Additional options including callbacks
                                             @usage[[
                                             require("devcontainer.container").exec(
                                               "some_id",
                                               { command = "nvim", on_success = function() end, on_fail = function() end }
                                             )
                                             @usage]]


ContainerStopOpts                     *devcontainer.container.ContainerStopOpts*

    Fields: ~
        {on_success}  (function)


M.container_stop({opts})                 *devcontainer.container.container_stop*

    Parameters: ~
        {opts}  (ContainerStopOpts)  Additional options including callbacks

    Usage: ~
>lua
        require("devcontainer.container").container_stop(
          { "some_id" },
          { on_success = function() end, on_fail = function() end }
        )
<


                                    *devcontainer.container.ContainerCommitOpts*
ContainerCommitOpts

    Fields: ~
        {tag}  (string)


M.container_commit({container}, {opts})*devcontainer.container.container_commit*
    Commits passed container

    Parameters: ~
        {container}  (string)               id of containers to commit
        {opts}       (ContainerCommitOpts)  Additional options including callbacks

    Usage: ~
>lua
        require("devcontainer.container").container_commit(
          "some_id",
          { tag = "my_image", on_success = function() end, on_fail = function() end }
        )
<


ImageInspectOpts                       *devcontainer.container.ImageInspectOpts*

    Fields: ~
        {format?}      (string)    format passed to image inspect command
        {on_success?}  (function)


M.image_inspect({image}, {opts})          *devcontainer.container.image_inspect*
    Inspect image status

    Parameters: ~
        {image}  (string)            id of image
        {opts}   (ImageInspectOpts)  Additional options including callbacks

    Usage: ~
>lua
        require("devcontainer.container").image_inspect(
          "some_id",
          { on_success = function(response) end, on_fail = function() end }
        )
<


ImageContainsOpts                     *devcontainer.container.ImageContainsOpts*

    Fields: ~
        {on_success?}  (function)


                                         *devcontainer.container.image_contains*
M.image_contains({parent_image}, {child_image}, {opts})
    Checks if image contains another image

    Parameters: ~
        {parent_image}  (string)             id of image that should contain other image
        {child_image}   (string)             id of image that should be contained in the parent image
        {opts}          (ImageContainsOpts)  Additional options including callbacks

    Usage: ~
>lua
        require("devcontainer.container").image_contains(
          "some_id",
          "some_other_id",
          { on_success = function() end, on_fail = function() end }
        )
<


ImageRmOpts                                 *devcontainer.container.ImageRmOpts*

    Fields: ~
        {force?}      (boolean)   force deletion
        {on_success}  (function)


M.image_rm({opts})                             *devcontainer.container.image_rm*

    Parameters: ~
        {opts}  (ImageRmOpts)  Additional options including callbacks
                               @usage[[
                               require("devcontainer.container").image_rm(
                                 { "some_id" },
                                 { on_success = function() end, on_fail = function() end }
                               )
                               @usage]]


ContainerRmOpts                         *devcontainer.container.ContainerRmOpts*

    Fields: ~
        {force?}      (boolean)   force deletion
        {on_success}  (function)


M.container_rm({opts})                     *devcontainer.container.container_rm*

    Parameters: ~
        {opts}  (ContainerRmOpts)  Additional options including callbacks
                                   @usage[[
                                   require("devcontainer.container").container_rm(
                                     { "some_id" },
                                     { on_success = function() end, on_fail = function() end }
                                   )
                                   @usage]]


ContainerLsOpts                         *devcontainer.container.ContainerLsOpts*

    Fields: ~
        {all?}         (boolean)   show all containers, not only running
        {async?}       (boolean)   run async - true by default
        {on_success?}  (function)


M.container_ls({opts})                     *devcontainer.container.container_ls*
    Lists containers

    Parameters: ~
        {opts}  (ContainerLsOpts)  Additional options including callbacks
                                   @usage[[
                                   require("devcontainer.container").container_ls(
                                     { on_success = function(containers) end, on_fail = function() end }
                                   )
                                   @usage]]


==============================================================================
High level container utility functions            *devcontainer.container-utils*

Provides functions for interacting with containers
High-level functions

                *devcontainer.container-utils.ContainerUtilsGetContainerEnvOpts*
ContainerUtilsGetContainerEnvOpts

    Fields: ~
        {on_success}  (function)


                                *devcontainer.container-utils.get_container_env*
M.get_container_env({container_id}, {opts?})
    Returns env variables from passed container in success callback
    Env variables are retrieved using printenv

    Parameters: ~
        {container_id}  (string)
        {opts?}         (ContainerUtilsGetContainerEnvOpts)


    *devcontainer.container-utils.ContainerUtilsGetContainerWorkspaceFolderOpts*
ContainerUtilsGetContainerWorkspaceFolderOpts

    Fields: ~
        {on_success}  (function)


                              *devcontainer.container-utils.get_image_workspace*
M.get_image_workspace({image_id}, {opts?})
    Returns workspace folder of passed image in success callback
    Retrieved using image inspect

    Parameters: ~
        {image_id}  (string)
        {opts?}     (ContainerUtilsGetContainerWorkspaceFolderOpts)


==============================================================================
Main devcontainer module - used to setup the plugin               *devcontainer*

Provides setup function

DevcontainerAutocommandOpts           *devcontainer.DevcontainerAutocommandOpts*

    Fields: ~
        {init?}    (boolean|string)  set to true (or "ask" to prompt before stating) to enable automatic devcontainer start
        {clean?}   (boolean)         set to true to enable automatic devcontainer stop and clean
        {update?}  (boolean)         set to true to enable automatic devcontainer update when config file is changed


DevcontainerSetupOpts                       *devcontainer.DevcontainerSetupOpts*

    Fields: ~
        {config_search_start?}                  (function)                     provides starting point for .devcontainer.json search
        {workspace_folder_provider?}            (function)                     provides current workspace folder
        {terminal_handler?}                     (function)                     handles terminal command requests, useful for floating terminals and similar
        {devcontainer_json_template?}           (function)                     provides template for new .devcontainer.json files - returns table
        {nvim_installation_commands_provider?}  (function)                     provides table of commands for installing neovim in container
        {nvim_install_as_root?}                 (boolean)                      can be set to true to install neovim as root in container - usually not required
        {generate_commands?}                    (boolean)                      can be set to false to prevent plugin from creating commands (true by default)
        {autocommands?}                         (DevcontainerAutocommandOpts)  can be set to enable autocommands, disabled by default
        {log_level?}                            (LogLevel)                     can be used to override library logging level
        {container_env?}                        (table)                        can be used to override containerEnv for all started containers
        {remote_env?}                           (table)                        can be used to override remoteEnv when attaching to containers
        {disable_recursive_config_search?}      (boolean)                      can be used to disable recursive .devcontainer search
        {cache_images?}                         (boolean)                      can be used to cache images after adding neovim - true by default
        {attach_mounts?}                        (AttachMountsOpts)             can be used to configure mounts when adding neovim to containers
        {always_mount?}                         (table)


M.setup({opts?})                                            *devcontainer.setup*
    Starts the plugin and sets it up with provided options

    Parameters: ~
        {opts?}  (DevcontainerSetupOpts)


==============================================================================
Devcontainer plugin config module                          *devcontainer.status*

Provides access to current status and is used internally to update it
Don't change directly!
Can be used for read-only access

                                   *devcontainer.status.DevcontainerImageStatus*
DevcontainerImageStatus

    Fields: ~
        {image_id}           (string)  id of the image
        {source_dockerfile}  (string)  path to the file used to build the image
        {tmp_dockerfile?}    (string)  path to temporary dockerfile if add neovim was used


                                    *devcontainer.status.DevcontainerImageQuery*
DevcontainerImageQuery

    Fields: ~
        {image_id?}           (string)  id of the image
        {source_dockerfile?}  (string)  path to the file used to build the image


                               *devcontainer.status.DevcontainerContainerStatus*
DevcontainerContainerStatus

    Fields: ~
        {container_id}    (string)   id of the container
        {image_id}        (string)   id of the used image
        {autoremove}      (boolean)  true if this container was started with autoremove flag
        {workspace_dir?}  (string)   overriden workspace folder for this container


                                *devcontainer.status.DevcontainerContainerQuery*
DevcontainerContainerQuery

    Fields: ~
        {container_id?}  (string)  id of the container
        {image_id?}      (string)  id of the used image


                                 *devcontainer.status.DevcontainerComposeStatus*
DevcontainerComposeStatus

    Fields: ~
        {file}  (string)  path to compose file


                                   *devcontainer.status.DevcontainerBuildStatus*
DevcontainerBuildStatus

    Fields: ~
        {build_title}         (string)   description of the build
        {progress}            (number)   0-100 percentage
        {step_count}          (number)   number of steps to build
        {current_step}        (number)   current step
        {image_id?}           (string)   id of the built image
        {source_dockerfile?}  (string)   path to the file used to build the image
        {build_command}       (string)   command used to build the image
        {commands_run}        (string)   list of commands run by build (layers)
        {running}             (boolean)  true if still running


DevcontainerStatus                      *devcontainer.status.DevcontainerStatus*

    Fields: ~
        {images_built}  (table)


M.get_status()                                  *devcontainer.status.get_status*
    Returns current devcontainer status in a table

    Returns: ~
        (DevcontainerStatus)


M.find_container({opts})                    *devcontainer.status.find_container*
    Finds container with requested opts
    Read-only

    Parameters: ~
        {opts}  (DevcontainerContainerQuery)  required opts

    Returns: ~
        (DevcontainerContainerStatus)


M.get_latest_container()              *devcontainer.status.get_latest_container*
    Returns latest container
    Read-only

    Returns: ~
        (DevcontainerContainerStatus)


M.find_image({opts})                            *devcontainer.status.find_image*
    Finds image with requested opts
    Read-only

    Parameters: ~
        {opts}  (DevcontainerImageQuery)  required opts

    Returns: ~
        (DevcontainerImageStatus)


M.find_build({opts})                            *devcontainer.status.find_build*
    Finds build status with requested opts
    Read-only

    Parameters: ~
        {opts}  (DevcontainerBuildStatus)  required opts

    Returns: ~
        (DevcontainerBuildStatus)



EVENTS                                        *devcontainer-autocmd-events*

This plugin also provides autocmd events:

*DevcontainerBuildProgress*
  Emitted when build status changes. Useful for statusline updates.
  See |devcontainer.status.find_build|.

*DevcontainerImageBuilt*
  Emitted when an image is built with this plugin. Passes a table in `data`
  with `image_id`.

*DevcontainerImageRemoved*
  Emitted when an image is removed with this plugin. Passes a table in `data`
  with `image_id`.

*DevcontainerContainerStarted*
  Emitted when a container is started with this plugin. Passes a table in `data`
  with `container_id`.

*DevcontainerContainerStopped*
  Emitted when a container is stopped with this plugin. Passes a table in `data`
  with `container_id`.

*DevcontainerContainerCommitted*
  Emitted when a container is committed with this plugin. Passes a table in `data`
  with `container_id` and `tag`.

*DevcontainerContainerRemoved*
  Emitted when a container is removed with this plugin. Passes a table in `data`
  with `container_id`.

Example:
  autocmd User DevcontainerBuildProgress redrawstatus


ISSUES                                           *devcontainer-issues*

If you experience issues using plugin, please report them at
<https://codeberg.org/esensar/nvim-dev-container/issues>.

CONTRIBUTING                                     *devcontainer-contributing*

Feel free to look at already reported issues at
<https://codeberg.org/esensar/nvim-dev-container/issues>.
If available, check out CONTRIBUTING.md in the repository.
Otherwise, feel free to create a new issue or pull request.

VERSION                                          *devcontainer-version*

Version 0.3.0-dev

LICENSE                                          *devcontainer-license*

MIT License

Copyright (c) 2022 Ensar Sarajčić

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

vim:tw=78:ts=2:ft=help:norl: