vscode-open

This is a Visual Studio Code extension for opening files in your browser, or vice versa.

The main purpose of this extension is to be able to seamlessly move between your editor and the SCM/code review provider in your browser. You can open files or pull requests in your browser based off of selected lines in your editor, or conversely open a file in your editor from a given URI.

See the release notes for the list of recent changes.

Features

• Open files in your browser, using a file-to-URI mapping of your choice

  • Available in editor/explorer context menus
  • Default bindings:
    • Windows/Unix: Ctrl Alt O + O
    • Mac: ⌘⌥O + O

• Open files with selected lines in your browser, using a file-to-URI mapping of your choice

  • Available in editor/explorer context menus
  • Default bindings:
    • Windows/Unix: Ctrl Alt O + L
    • Mac: ⌘⌥O + L

• Open pull requests for selected lines in your browser, using a Git provider of your choice

  • Specifically, this opens the pull request that was merged for the currently selected line (i.e. what would appear in git blame)
  • Available in editor context menus
  • Default bindings:
    • Windows/Unix: Ctrl Alt O + P
    • Mac: ⌘⌥O + P

• Open files in VSCode from URIs, using a URI-to-file mapping of your choice

  • Supports line numbers in the URIs — if present, will select the given lines and scroll to the selection
  • Default bindings:
    • Windows/Unix: Ctrl Alt O + U
    • Mac: ⌘⌥O + U

Configuration

Mappings

Mappings are the main settings that determine how to generate file paths/URIs/PRs.

• open.fileMappings

  • Type: object[]
  • This configures a list of file mappings. Each mapping declares a file path pattern that maps files to URIs. Only the first mapping matching the file path will be applied.
  • File mappings have the following schema: |Property Name|Required|Description| |-------------|--------|-----------| |pattern|Yes|Pattern that matches file paths; paths matching this pattern will have the mapping in question applied.| |output|Yes|Pattern that generates URIs; will be applied to the path captured by pattern.| |lineSeparator|No|Optional parameter for configuring the text used to denote the line numbers in the URI, e.g. the # in #123-124. Defaults to #.| |linePrefix|No|Optional parameter for configuring the prefix used for rendering line numbers in the URI, e.g. setting this to L will render the line numbers as L123-L124. Defaults to nothing.| |lineRangeSeparator|No|Optional parameter for configuring the text used to denote the line number range in the URI, e.g. the - in #123-124. Defaults to -.|

• open.prMappings

  • Type: object[]
  • This configures a list of file mappings for pull requests. Each mapping declares a file path pattern and opens pull requests for matched files.
  • PR mappings have the following schema: |Property Name|Required|Description| |-------------|--------|-----------| |pattern|Yes|Pattern that matches file paths; paths matching this pattern will have the mapping in question applied.| |provider|Yes|Configuration for code review provider.|
  • The provider setting has the following schema: |Property Name|Required|Description| |-------------|--------|-----------| |type|Yes|Provider type; supported values are: phabricator, github (Note: only public GitHub repos are currently supported).| |base|Yes|Base URL for provider.|

• open.uriMappings

  • Type: object[]
  • This configures a list of URI mappings. Each mapping declares a URI pattern that maps URIs to files.
  • URI mappings have the following schema: |Property Name|Required|Description| |-------------|--------|-----------| |pattern|Yes|Pattern that matches URIs; URIs matching this pattern will have the mapping in question applied.| |output|Yes|Pattern that generates file paths; will be applied to the URI captured by pattern.| |lineSeparator|No|Optional parameter for configuring the text used to denote the line numbers in the URI, e.g. the # in #123-124. Defaults to #.| |linePrefix|No|Optional parameter for configuring the prefix used for rendering line numbers in the URI, e.g. setting this to L will recognize line numbers such as L123-L124. Default support is for no line prefix or a line prefix of L.| |lineRangeSeparator|No|Optional parameter for configuring the text used to denote the line number range in the URI, e.g. the - in #123-124. Defaults to -.|

Variables

There are a number of special variables that are supported by this extension, which make it possible/easier to generate mappings. Variables can be used in the patterns that are required for various mappings, using the format ${category:value}. Some variables may take additional values, which are further separated by additional colons, e.g. ${category:value_1:value_2}.

env

This category surfaces environment variables, specifically the environment variables available to the Node process running the extension.

Example:

${env:HOME}/myrepo/file.py
# Output: /Users/me/myrepo/file.py

editor

This category surfaces information about the current editor context. Many of these overlap with the standard VSCode variables that are available as part of VSCode's own configuration files.

Examples:

# Assume multiple opened workspace folders, current file is /myrepo/dir/file.py

${editor:workspaceFolder:myrepo}
# Output: /myrepo

${editor:workspaceFolderBasename:myrepo}
# Output: myrepo

${editor:relativeFile:myrepo}
# Output: /dir/file.py

${editor:relativeFileDirname:myrepo}
# Output: /dir

# Assume single opened workspace folder, current file is /myrepo/dir/file.py

${editor:workspaceFolder}
# Output: /myrepo

${editor:workspaceFolderBasename}
# Output: myrepo

${editor:relativeFile}
# Output: /dir/file.py

${editor:relativeFileDirname}
# Output: /dir

${editor:file}
# Output: /myrepo/dir/file.py

${editor:fileBasename}
# Output: file.py

${editor:fileBasenameNoExtension}
# Output: file

${editor:fileDirname}
# Output: /myrepo/dir

${editor:fileExtname}
# Output: .py

${editor:lines}
# Output: e.g. [#12](https://github.com/alexander-yu/vscode-open/issues/12) or [#12](https://github.com/alexander-yu/vscode-open/issues/12)-14 (the default format)

${editor:currentCommit}
# Output: e.g. 6081948371a180586a806a214202e44c2f922a42

match

This category allows you to extract any regex capture groups from the input patterns of mappings. The value of the variable must be the name of a valid capture group in the input pattern.

Example:

${match:group_1}/${match:group_2}
# Input pattern: (?<group_1>[A-Za-z]+)_(?<group_2>[0-9]+).txt
# Input text: hello_123.txt
# Output: hello/123

regex

This category provides some standard regex templates to use. This will be subsituted by the appropriate regex template, with a capture group whose name is equal to the template name (i.e. you can use this in conjunction with match variables).

Example Configuration

{
    "open.fileMappings": [
        {

            "pattern": "src/static/(?<mdFileWithoutExt>.+)\\.md$",
            "output": "https://host.example.com/docs/${match:mdFileWithoutExt}"
        },
        {
            "pattern": "${editor:file}",
            "output": "https://host.example.com/repo/blob/${editor.currentCommit}/${editor:relativeFile}${editor:lines}",
            "lineSeparator": "#",
            "linePrefix": "L"
        }
    ],
    "open.prMappings": [
        {
            "pattern": "${editor:file}",
            "provider": {
                "type": "phabricator",
                "base": "https://phabricator.example.com"
            }
        }
    ],
    "open.uriMappings": [
        {
            "pattern": "https://host.example.com/repo/${regex:file}${regex:lines}",
            "output": "${editor:workspaceFolder}/${match:file}${match:lines}",
            "lineSeparator": "#"
        }
    ]
}