Use ripgrep to find TODO tags and display the results in a tree view
Clone or download

README.md

Todo Tree

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

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.

Foreground and background colours can be one of "red", "green", "blue", "yellow", "magenta", "cyan" or "grey". RGB values can also be used.

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.

type - used to control how much is highlighted in the editor. Valid values are:

  • tag - highlights just the tag
  • text - highlights the tag and any text after the tag
  • line - highlights the entire line containing the tag

Example:

"todo-tree.defaultHighlight": {
    "icon": "alert",
    "type": "text",
    "foreground": "red",
    "background": "white",
    "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.

Installing

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!

Source Code

The source code is available on GitHub here.

Controls

The tree view header contains the following buttons:

- Show the tree view as a flat list, with the full filename for each TODO
- 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
- Collapse all tree nodes
- Expand all tree nodes
- Rebuild the tree

Commands

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.

Configuration

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.icons1 {} Use alternative icons from the octicon set for specific tags, e.g. {"TODO":"pin", "FIXME":"issue-opened"}
todo-tree.iconColour1 "green" Use this to change the colour of the icon for TODOs in the tree. Can be hex (e.g. "#FF80FF" ) or one of "red", "green", "blue", "yellow", "magenta", "cyan" or "grey".
todo-tree.iconColours1 {} Use this if you need different icon colours based on the type of tag. The colours can be hex codes, or from the list above, and the match can be a javascript regex. e.g. {"TODO": "#FF80FF","^BUG": "red"}. Note: The colours are applied after the search results, so don't forget to modify todo-tree.tags if you want to add new tags!
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.highlight1 false Set this to true to highlight tags in files.
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 opened 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.expanded1 false Set to true if you want new trees to be expanded by default
todo-tree.flat1 false Set to true if you want new trees to be flat by default
todo-tree.grouped1 false Set to true if you want new trees to be grouped by default

1 Deprecated - Please use todo-tree.defaultHighlight and todo-tree.customHighlight instead.

2 Only applies to new workspaces. Once the view has been changed in the workspace, the current state is stored.

Excluding files and folders

To exclude folders from your search, use the todo-tree.globs setting. For example, if you want to ignore everything in subfolders called dist, set it to [ "!dist" ].

For more information on glob patterns, see here.

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.

Known Issues

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.

Donate

If you find this extension useful, please feel free to donate here. Thanks!

Credits

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