Skip to content

How it works

Jump to bottom
Alessandro Fulgini edited this page Nov 3, 2022 · 1 revision

Here I will give some introspection on how VSCode stores recent items and how they can be opened. You might ask: why is this on the Wiki? Because I don't have a blog.

Recently opened items

VSCode stores its state in a local database inside its config directory: ~/.config/Code/User/globalStorage/state.vscdb.

It contains a single table (ItemTable), where each row is a JSON key-value pair. Key history.recentlyOpenedPathsList contains a list of recently opened entries. By taking a look at the source code we can see that there are three types of entries:

After choosing a suitable VSCode flavor, the plugin reads these structures from the database.

Each of the above entries has:

  • A URI that identifies what workspace, file or folder to open.
    • For items on the local filesystem, the form is file:///path/to/file/or/folder
    • For remote items, the form is vscode-remote://{remote_authority}/path/to/file/or/folder
  • An (optional) remote authority in the form {type}+{id} which identifies the remote. Type can be wsl, ssh-remote, dev-container, ...
  • An (optional) label that is shown to the user (if not set we derive it from the URI)

Opening the items

Opening local files and folders is easy enough: we extract the fs path from the URL and call code /path/to/file/or/folder, but what about remote items? Well, we have two choices.

Using the remote CLI

VSCode provides a simple way to open remote projects from the terminal:

# For workspaces
code --remote {remote_authority} /path/to/project.code-workspace

# For folders
code --folder-uri vscode-remote://{remote_authority}/path/to/folder

# For files
code --file-uri vscode-remote://{remote_authority}/path/to/file

Thankfully, they also work for file:// URIs. Another advantage of this approach is that we can disambiguate between files and folders, so VSCode doesn't have to guess. (Unfortunately, this doesn't hold for the next option, so we choose this.)

Using the URL handler

VSCode comes with a builtin URI handler that is able to handle both cases. This feature is well-known, albeit not well-documented. Looking at the source code for the URI handler and at some issues (#656, #4779) we can make sense of how it works.

The scheme of the URI identifies the VSCode flavor: vscode://, vscode-insiders:// or vscodium://. The rest is the same as the URI we saw before, but "pushed back" by one position.

# Local URI (same as file://path/to/file/or/folder)
vscode://file/path/to/file/or/folder

# Remote URI (same as vscode-remote://ssh+myserver.dev/...)
vscode://vscode-remote/ssh+myserver.dev/path/to/file/or/folder

We can then open these URIs by using:

  • xdg-open {uri}, or
  • code --open-url {uri}

That's all for now, I hope you learnt something®.

Clone this wiki locally