This extension helps you efficiently manage and track files or specific locations within your projects. Use it to leave breadcrumbs while debugging, navigate your code more easily, or quickly switch between tasks by bookmarking all open editors.
- Save bookmarks globally or per workspace.
- Organize bookmarks into folders.
- Manage bookmarks via commands, UI controls, and gestures (e.g. drag-and-drop).
A bookmark is a reference to a specific location within a document. Bookmarks are grouped as Workspace (tied to the current workspace) or Global (independent of any workspace). They use absolute URIs to describe their locations, ensuring compatibility with any file system supported by VS Code. The UI dynamically adjusts how bookmarks are displayed, such as showing relative paths when applicable to the current workspace.
A bookmark's identity is tied to its URL, which normally includes a one-based line fragment (e.g., file://workspace/file.rb#L1) or a line range (e.g., file://workspace/file.rb#L44-L133).
A folder is a container for bookmarks. They are not related to the file system hierarchy associated to any of the contained bookmarks.
The only constraint imposed by folders is that a given bookmark must be unique within it. For example, you can add a bookmark to file://workspace/file.rb#L1 to every single folder, but only once per folder. Every bookmark is its own entity, so if you change the display name of one of them, only the specific bookmark is updated.
The Bookmarks View is the main UI component for this extension. Bookmarks are split into two categories:
- Global: shows bookmarks that are always available, regardless of what the current workspace is.
- Workspace: shows bookmarks associated with the currently open workspace, if any.
You can change the display mode of the tree:
- Name: shows the file name and target line range. A path hint is shown as a description.
- Path: shows the file path relative to the currently open workspace. The associated line range is shown as a description.
There are two commands available to add a bookmark: Bookmarks: Bookmark Editor (Global) and Bookmarks: Bookmark Editor (Workspace). Both work on the active editor and add a bookmark to the appropriate category. When a bookmark is created using any of these commands, the current line location or selection is captured.
The following commands are available for other extensions to use: bookmarks.addBookmark.global and bookmarks.addBookmark.workspace. They take a single argument that is the path or URI to the file to bookmark.
Line information can be added by appending a fragment to the URI in the format: L<lineNumber>, with lineNumber being a 1-based index.
Editors can be dragged onto the tree, and they will be bookmarked. Additionally, you can drag items between categories to move them. When a bookmark is created bu dragging a file onto the Bookmarks view, line information is not captured.
There is a + button available on each category node (Global, Workspace) that bookmarks the selection in the active editor.
There are two commands available: Bookmarks: Remove All (Global) and Bookmarks: Remove All (Workspace).
The following commands are available for other extensions to use:
bookmarks.removeBookmark.globalandbookmarks.removeBookmark.workspace. They take a single argument that is the path or URI to the file to remove.bookmarks.removeBookmarks.globalandbookmarks.removeBookmarks.workspace. They take no argument and remove all bookmarks from the corresponding category.
There is an X button on each bookmark node, as well as for each category and the tree view header. These buttons allow you to remove individual bookmarks, all bookmarks under a specific category, or all bookmarks in the tree view. Additionally, the context menu for each category node includes a Remove All action to clear all bookmarks within that category.
Assigning a custom display name to a bookmark affects how it is presented in the UI. This can be used to provide a meaningful name, such as "Bug Location".
In the Display Name context menu for a given bookmark, use:
- Update… to modify the display name of the bookmark.
- Remove to delete the custom display name and revert to the default.
Updating the line information helps keep bookmarks in-sync with changes to their targets or to fix an incorrect value. Bookmarks can only target full lines at this time.
In the Line or Range context menu for a given bookmark, use:
- Update… to update the line or line range.
Attach text notes to a bookmark for reference. Notes appear in the bookmark’s tooltip.
In the Notes context menu for a given bookmark, use:
- Update… to modify the note text.
- Remove to delete the note.
There are two commands, Bookmarks: Go to Next in Current Editor and Bookmarks: Go to Previous in Current Editor, that can be used to jump between bookmarks set in the current editor.
The following commands are available for other extensions to use: bookmarks.navigate.next.editor and bookmarks.navigate.previous.editor. They take a single optional argument, which is the path or URI to the file to navigate to (it will be opened if needed).
Bookmarks are expected to be rendered as markers on the corresponding editor gutter. This is supported via the Bookmarks: Toggle In-Editor Markers command but it is disabled by default due to VSCode #5923 which causes these markers to affect the breakpoint markers in some cases (unacceptable experience). You can also use the Hide In-Editor Markers and Show In-Editor Markers actions in the Bookmarks view menu.
You can add breakpoints to covered lines via the gutter's context menu when markers are visible.