• Public
  • Public/Protected
  • All

Namespace workspace



A file system instance that allows to interact with local and remote files, e.g. workspace.fs.readDirectory(someUri) allows to retrieve all entries of a directory or workspace.fs.stat(anotherUri) returns the meta data for a file.

isTrusted: boolean

When true, the user has explicitly trusted the contents of the workspace.

name: string | undefined

The name of the workspace. undefined when no folder has been opened.

rootPath: string | undefined

The folder that is open in the editor. undefined when no folder has been opened.


Use workspaceFolders instead.

textDocuments: readonly TextDocument[]

All text documents currently known to the system.

workspaceFile: Uri | undefined

The location of the workspace file, for example:


Depending on the workspace that is opened, the value will be:

  • undefined when no workspace or a single folder is opened
  • the path of the workspace file as Uri otherwise.

Note: it is not advised to use workspace.workspaceFile to write configuration data into the file.

workspaceFolders: readonly WorkspaceFolder[] | undefined

List of workspace folders or undefined when no folder is open. Note that the first entry corresponds to the value of rootPath.



  • Make changes to one or many resources or create, delete, and rename resources as defined by the given workspace edit.

    All changes of a workspace edit are applied in the same order in which they have been added. If multiple textual inserts are made at the same position, these strings appear in the resulting text in the order the 'inserts' were made. Invalid sequences like 'delete file a' -> 'insert text in file a' cause failure of the operation.

    When applying a workspace edit that consists only of text edits an 'all-or-nothing'-strategy is used. A workspace edit with resource creations or deletions aborts the operation, e.g. consecutive edits will not be attempted, when a single edit fails.


    Returns Thenable<boolean>

    A thenable that resolves when the edit could be applied.

  • asRelativePath(pathOrUri: string | Uri, includeWorkspaceFolder?: boolean): string | undefined
  • Returns a path that is relative to the workspace folder or folders.

    When there are no workspace folders or when the path is not contained in them, the input is returned.


    • pathOrUri: string | Uri

      A path or uri. When a uri is given its fsPath is used.

    • Optional includeWorkspaceFolder: boolean

      When true and when the given path is contained inside a workspace folder the name of the workspace is prepended. Defaults to true when there are multiple workspace folders and false otherwise.

    Returns string | undefined

    A path relative to the root or the input.

  • createFileSystemWatcher(globPattern: GlobPattern, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher
  • Find files across all workspace folders in the workspace.


    findFiles('**​/*.js', '**​/node_modules/**', 10)


    • include: GlobPattern

      A glob pattern that defines the files to search for. The glob pattern will be matched against the file paths of resulting matches relative to their workspace. Use a relative pattern to restrict the search results to a workspace folder.

    • Optional exclude: null | GlobPattern

      A glob pattern that defines files and folders to exclude. The glob pattern will be matched against the file paths of resulting matches relative to their workspace. When undefined only default excludes will apply, when null no excludes will apply.

    • Optional maxResults: number

      An upper-bound for the result.

    • Optional token: CancellationToken

      A token that can be used to signal cancellation to the underlying search engine.

    Returns Thenable<Uri[]>

    A thenable that resolves to an array of resource identifiers. Will return no results if no workspace folders are opened.

  • Get a workspace configuration object.

    When a section-identifier is provided only that part of the configuration is returned. Dots in the section-identifier are interpreted as child-access, like { myExt: { setting: { doIt: true }}} and getConfiguration('myExt.setting').get('doIt') === true.

    When a scope is provided configuration confined to that scope is returned. Scope can be a resource or a language identifier or both.


    • Optional section: string

      A dot-separated identifier.

    • Optional scope: null | ConfigurationScope

      A scope for which the configuration is asked for.

    Returns WorkspaceConfiguration

    The full configuration or a subset.

  • onDidGrantWorkspaceTrust(listener: ((e: void) => any), thisArgs?: any, disposables?: Disposable[]): Disposable
  • An event that is emitted when a text document will be saved to disk.

    Note 1: Subscribers can delay saving by registering asynchronous work. For the sake of data integrity the editor might save without firing this event. For instance when shutting down with dirty files.

    Note 2: Subscribers are called sequentially and they can delay saving by registering asynchronous work. Protection against misbehaving listeners is implemented as such:

    • there is an overall time budget that all listeners share and if that is exhausted no further listener is called
    • listeners that take a long time or produce errors frequently will not be called anymore

    The current thresholds are 1.5 seconds as overall time budget and a listener can misbehave 3 times before being ignored.


    Returns Disposable

  • Opens a document. Will return early if this document is already open. Otherwise the document is loaded and the didOpen-event fires.

    The document is denoted by an uri. Depending on the scheme the following rules apply:

    • file-scheme: Open a file on disk, will be rejected if the file does not exist or cannot be loaded.
    • untitled-scheme: A new file that should be saved on disk, e.g. untitled:c:\frodo\new.js. The language will be derived from the file name.
    • For all other schemes the registered text document content providers are consulted.

    Note that the lifecycle of the returned document is owned by the editor and not by the extension. That means an onDidClose-event can occur at any time after opening it.


    • uri: Uri

      Identifies the resource to open.

    Returns Thenable<TextDocument | undefined>

    A promise that resolves to a document.

  • A short-hand for openTextDocument(Uri.file(fileName)).




    • fileName: string

      A name of a file on disk.

    Returns Thenable<TextDocument | undefined>

    A promise that resolves to a document.

  • Opens an untitled text document. The editor will prompt the user for a file path when the document is to be saved. The options parameter allows to specify the language and/or the content of the document.


    • Optional options: { content?: string; language?: string }

      Options to control how the document will be created.

      • Optional content?: string
      • Optional language?: string

    Returns Thenable<TextDocument | undefined>

    A promise that resolves to a document.

  • registerFileSystemProvider(scheme: string, provider: FileSystemProvider, options?: { isCaseSensitive?: boolean; isReadonly?: boolean }): Disposable
  • Register a filesystem provider for a given scheme, e.g. ftp.

    There can only be one provider per scheme and an error is being thrown when a scheme has been claimed by another provider or when it is reserved.


    • scheme: string

      The uri-scheme the provider registers for.

    • provider: FileSystemProvider

      The filesystem provider.

    • Optional options: { isCaseSensitive?: boolean; isReadonly?: boolean }

      Immutable metadata about the provider.

      • Optional Readonly isCaseSensitive?: boolean
      • Optional Readonly isReadonly?: boolean

    Returns Disposable

    A disposable that unregisters this provider when being disposed.

  • Register a timeline provider.

    Multiple providers can be registered. In that case, providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.


    • scheme: string | string[]

      A scheme or schemes that defines which documents this provider is applicable to. Can be * to target all documents.

    • provider: TimelineProvider

      A timeline provider.

    Returns Disposable

    A disposable that unregisters this provider when being disposed.

  • saveAll(includeUntitled?: boolean): Thenable<boolean>
  • Save all dirty files.


    • Optional includeUntitled: boolean

      Also save files that have been created during this session.

    Returns Thenable<boolean>

    A thenable that resolves when the files have been saved.

  • updateWorkspaceFolders(start: number, deleteCount: undefined | null | number, ...workspaceFoldersToAdd: { name?: string; uri: Uri }[]): boolean
  • This method replaces deleteCount workspace folders starting at index start by an optional set of workspaceFoldersToAdd on the theia.workspace.workspaceFolders array. This "splice" behavior can be used to add, remove and change workspace folders in a single operation.

    If the first workspace folder is added, removed or changed, the currently executing extensions (including the one that called this method) will be terminated and restarted so that the (deprecated) rootPath property is updated to point to the first workspace folder.

    Use the onDidChangeWorkspaceFolders() event to get notified when the workspace folders have been updated.

    Example: adding a new workspace folder at the end of workspace folders

    workspace.updateWorkspaceFolders(workspace.workspaceFolders ? workspace.workspaceFolders.length : 0, null, { uri: ...});

    Example: removing the first workspace folder

    workspace.updateWorkspaceFolders(0, 1);

    Example: replacing an existing workspace folder with a new one

    workspace.updateWorkspaceFolders(0, 1, { uri: ...});

    It is valid to remove an existing workspace folder and add it again with a different name to rename that folder.

    Note: it is not valid to call updateWorkspaceFolders() multiple times without waiting for the onDidChangeWorkspaceFolders() to fire.


    • start: number

      the zero-based location in the list of currently opened workspace folders from which to start deleting workspace folders.

    • deleteCount: undefined | null | number

      the optional number of workspace folders to remove.

    • Rest ...workspaceFoldersToAdd: { name?: string; uri: Uri }[]

      the optional variable set of workspace folders to add in place of the deleted ones. Each workspace is identified with a mandatory URI and an optional name.

    Returns boolean

    true if the operation was successfully started and false otherwise if arguments were used that would result in invalid workspace folder state (e.g. 2 folders with the same URI).