-
Notifications
You must be signed in to change notification settings - Fork 14
/
devcontainer.txt
1169 lines (834 loc) · 42.9 KB
/
devcontainer.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*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 jsonc 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.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)
*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 }
)
<
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)
==============================================================================
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
{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