How to use Folders outside the Workspace root in a .devcontainer
In my recent years of software development using VSCode, I have adopted the practice of using workspaces and .devcontainers.
In this article, I will demonstrate how to address a particular issue that arises when your .code-workspace file references a folder which is outside the workspace root.
First, let’s understand this workspace configuration without the additional complexity of .devcontainers
Visual Example
Below, see the local file system and how a workspace file can reference a sibling folder (outside the workspace root)
(I have named the folders project-folder and external-folder for clarity)
Notice how the file references folders based on the workspace root. The parent link (..) is used to reference a folder outside the root.
This all works fine; however, we would like to also get the benefits of the .devcontainer. When we add the .devcontainer files and attempt to open, VSCode will prompt us with this warning:
Why does this issue occur?
As shown above, normally referencing folders outside the root is not an issue. However, when you use a .devcontainer, this implicitly mounts the folder containing your source code into the container in order to be a a useful development environment and allow editing code. This default which mounts your source code is unaware of how to mount this external folder referenced in the workspace so it will not exist in the container file system and thus cannot be referenced as the warning image says.
If you attempt to open a .devcontainer without applying the fixes I suggest below you will see this warning in VSCodes file explorer
Why would you want to reference a folder outside the workspace?
I agree this practice is likely rare and best avoided; however, I have been using a shared-resources folder with common deployment scripts that my other projects reference. In more robust cases this would likely be distributed package; however, locally referencing the folder allows quick editing. After all it worked well until I started adding .devcontainers.
How to solve the issue?
Override the default mounts to mimic the folder hierarchy of the local file system.
This allows the paths specified in the workspace file to resolve correctly and external folder to be exposed internally.
How to override the default mounts?
Let’s look at the documentation to understand the defaults
Documentation
Default .devcontainer Workspace Mount
"workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind",
"workspaceFolder": "/workspace",Modified .devcontainer Workspace Mount and Additional Mount
Remember, the goal is to mimic the same relationship of the local folder hierarchy inside the container. This means the external-folder should be mounted to a location as a sibling of project-folder .
"workspaceMount": "source=${localWorkspaceFolder},target=/workspace/dummyFolderOne/projectFolder,type=bind",
"workspaceFolder": "/workspace/dummyFolderOne/projectFolder",
"mounts": [
{
"source": "${localWorkspaceFolder}/../external-folder",
"target": "/workspace/dummyFolderOne/external-folder",
"type": "bind"
}
]With updated settings, Rebuild the container, and view the external-folder the same as local experience! 🥳
You can also verify container file system is structured how you expect
This now completes the demonstration. Below is more explanation about the solution and troubleshooting you may find useful.
Note about the use of “dummyFolderOne”
There seem to be some inconsistency in names allowed when customizing the .devcontainer mounts.
For example, by default the workspace mount would mount to /workspace/project-folder. This means I should only have to add the mount of external-folder to /workspace/external-folder
Strangely does not work and I am not sure why.
This is why I added the extra “dummyFolderOne” to the path.
Also, if the target leave folder uses same name as the actual workspace folder name it fails.
For example, it would be expected to use /workspace/dummyFolderOne/project-folder ; however, this also fails.
This is why I slightly changed the target location to projectFolder
How to troubleshoot .devcontainer mounts?
Based on the strange errors above, the mounts may fail and may result in this error:
To debug the mounts of the .devcontainer and observe the resolved file paths on the local vs container file system you can use the .devcontainer build log and terminal search feature:
Support
If you found this article helpful, consider buying me a coffee🍵
