This extension quickly searches (using ripgrep) your workspace for comment tags like TODO and FIXME, and displays them in a tree view in the explorer pane. Clicking a TODO within the tree will open the file and put the cursor on the line containing the TODO.
Found TODOs can also be highlighted in open files.
Note: The tree will only appear in the explorer pane when the extension finds some TODOs.
Highlighting tags is configurable. Use defaultHighlight to set up highlights for all tags. If you need to configure individual tags differently, use customHighlight. If settings are not specified in customHighlight, the value from defaultHighlight is used. If a setting is not specified in defaultHighlight then the older, deprecated icon, iconColour and iconColours settings are used.
Both defaultHighlight and customHighlight allow for the following settings:
foreground - used to set the foreground colour of the highlight in the editor and the marker in the ruler.
background - used to set the background colour of the highlight in the editor.
opacity - percentage value used with the background colour. 100% will produce an opaque background which will obscure selection and other decorations.
Foreground and background colours can be one of "red", "green", "blue", "yellow", "magenta", "cyan", "grey", "white" or "black". RGB values can also be used (e.g. "#80FF00").
icon - used to set a different icon in the tree view. Must be a valid octicon - will default to a tick if it's not.
iconColour - used to set the colour of the icon in the tree. If not specified, it will try to use the foreground colour, the background colour and then the older settings, in that order.
rulerColour - used to set the colour of the marker in the overview ruler. If not specified, it will to use the foreground colour.
rulerLane - used to set the lane for the marker in the overview ruler. If not specified, it will default to the right hand lane. Use one of "left", "center", "right", or "full".
type - used to control how much is highlighted in the editor. Valid values are:
tag- highlights just the tagtext- highlights the tag and any text after the tagline- highlights the entire line containing the tag
Example:
"todo-tree.defaultHighlight": {
"icon": "alert",
"type": "text",
"foreground": "red",
"background": "white",
"opacity": 50,
"iconColour": "blue"
},
"todo-tree.customHighlight": {
"TODO": {
"icon": "check",
"type": "line"
},
"FIXME": {
"foreground": "black",
"iconColour": "yellow"
}
}
Note: The highlight configuration is separate from the settings for the search. Adding settings in customHighlight does not automatically add the tags into todo-tree.tags.
You can install the latest version of the extension via the Visual Studio Marketplace here.
Alternatively, open Visual Studio code, press Ctrl+P or Cmd+P and type:
> ext install todo-tree
Note: Don't forget to reload the window to activate the extension!
The source code is available on GitHub here.
The tree view header contains the following buttons:
- Collapse all tree nodes
- Expand all tree nodes
- Show the tree view as a flat list, with the full filename for each TODO
- Show the view as a list of tags
- Show the tree view as a tree with expandable nodes for each folder (default)
- Group the TODOs in the tree by the tag
- Organise the TODOs by file (default)
- Only show items in the tree which match the entered filter text
- Remove any active filter
- Rebuild the tree
To make it easier to configure the tags, there are two commands available:
todo-tree: Add Tag - allows entry of a new tag for searching
todo-tree: Remove Tag - shows a list of current tags which can be selected for removing
Note: The Remove Tag command can be used to show current tags - just press Escape or Enter with out selecting any to close it.
The extension can be customised as follows:
| Setting | Default | Description |
|---|---|---|
| todo-tree.rootFolder | "" | By default, any open workspaces will have a tree in the view. Use this to force another folder to be the root of the tree. You can include environment variables and also use ${workspaceFolder}. e.g. "todo-tree.rootFolder": "${workspaceFolder}/test" or "todo-tree.rootFolder": "${HOME}/project". Note: Other open files (outside of the rootFolder) will be shown (as they are opened) with their full path in brackets. |
| todo-tree.tags | ["TODO","FIXME"] | This defines the tags which are recognised as TODOs. This list is automatically inserted into the regex. |
| todo-tree.regex | "((//|#|<!--|;|/\\*)\\s*($TAGS)|^\\s*- \\[ \\])" | This defines the regex used to locate TODOs. By default, it searches for tags in comments starting with //, #, ;, <!-- or /*. This should cover most languages. However if you want to refine it, make sure that the ($TAGS) is kept. The second part of the expression allows matching of Github markdown task lists. Note: This is a Rust regular expression, not javascript. |
| todo-tree.regexCaseSensitive | true | Set to false to allow tags to be matched regardless of case. |
| todo-tree.includeGlobs | [] | Globs for use in limiting search results by inclusion, e.g. [\"**/unit-tests/*.js\"] to only show .js files in unit-tests subfolders. Globs help
|
| todo-tree.excludeGlobs | [] | Globs for use in limiting search results by exclusion (applied after includeGlobs), e.g. [\"**/*.txt\"] to ignore all .txt files |
| todo-tree.includedWorkspaces | [] | A list of workspace names to include as roots in the tree (wildcards can be used). An empty array includes all workspace folders |
| todo-tree.excludedWorkspaces | [] | A list of workspace names to exclude as roots in the tree (wildcards can be used). |
| todo-tree.ripgrep | "" | Normally, the extension will locate ripgrep itself as and when required. If you want to use an alternate version of ripgrep, set this to point to wherever it is installed. |
| todo-tree.ripgrepArgs | "" | Use this to pass additional arguments to ripgrep. e.g. "-i" to make the search case insensitive. Use with caution! |
| todo-tree.ripgrepMaxBuffer | 200 | By default, the ripgrep process will have a buffer of 200KB. However, this is sometimes not enough for all the tags you might want to see. This setting can be used to increase the buffer size accordingly. |
| todo-tree.showInExplorer | true | The tree is shown in the explorer view and also has it's own view in the activity bar. If you no longer want to see it in the explorer view, set this to false. |
| todo-tree.filterCaseSensitive | false | Use this if you need the filtering to be case sensitive. Note: this does not the apply to the search. |
| todo-tree.highlightDelay | 500 | The delay before highlighting (milliseconds). |
| todo-tree.trackFile | true | Set to false if you want to prevent tracking the open file in the tree view. |
| todo-tree.showBadges | true | Set to false to disable SCM status and badges in the tree. Note: This also unfortunately turns off themed icons. |
| todo-tree.showTagsFromOpenFilesOnly | false | Set to true to only show TODOs in open files. |
| todo-tree.defaultHighlight | {} | Set default highlights. E.g. {"foreground":"white","background":"red","icon":"check","type":"text"}
|
| todo-tree.customHighlight | {} | Set highlights per tag. E.g. {"TODO":{"foreground":"white","type":"text"},"FIXME":{"icon":"beaker"}}
|
| todo-tree.expanded* | false | Set to true if you want new views to be expanded by default |
| todo-tree.flat* | false | Set to true if you want new views to be flat by default |
| todo-tree.grouped* | false | Set to true if you want new views to be grouped by default |
| todo-tree.tagsOnly* | false | Set to true if you want new views with tags only by default |
| todo-tree.sortTagsOnlyViewAlphabetically | false | Sort items in the tags only view alphabetically instead of by file and line number |
| todo-tree.statusBar | none | What to show in the status bar - nothing (none), total count (total), counts per tag (tags) or the counts for the top three tags (top three) |
| todo-tree.showCountsInTree | false | Set to true to show counts of TODOs in the tree |
| todo-tree.labelFormat | ${tag} ${after} | Format of the TODO item labels. Available placeholders are ${line}, ${column}, ${tag}, ${before} (text from before the tag) and ${after} (text from after the tag). |
* Only applies to new workspaces. Once the view has been changed in the workspace, the current state is stored.
To restrict the set of folders which is searched, you can define todo-tree.includeGlobs. This is an array of globs which the search results are matched against. If the results match any of the globs, they will be shown. By default the array is empty, which matches everything.
To exclude folders/files from your search you can define todo-tree.excludeGlobs. If the search results match any of these globs, then the results will be ignored.
There is also support
Note: By default, ripgrep ignores files and folders from your .gitignore or .ignore files. If you want to include these files, set todo-tree.ripgrepArgs to --no-ignore.
Grouping by tag will only work when your configuration defines the tags using the todo-tree.tags setting. Older versions of the extension had the tags directly defined in the todo-tree.regex whereas now, the regex replaces $TAGS with the contents of todo-tree.tags.
Grouping by tag doesn't work for markdown task list items as there is no tag to group with. The tree will show the files alongside the tag groups.
Tracking the file in the tree view when grouping by tag will reveal the first tag found.
When there is no current workspace, default icons will be shown in the tree.
If you find this extension useful, please feel free to donate here. Thanks!
Uses a modified version of ripgrep-js.
Main icons originally made by Freepik from www.flaticon.com is licensed by CC 3.0 BY
Tree view icons made by Vaadin from www.flaticon.com is licensed by CC 3.0 BY
Tag icons made by Dave Gandy from www.flaticon.com is licensed by CC 3.0 BY
Tags Icon made by Vectors Market from www.flaticon.com is licensed by CC 3.0 BY