Home

Working with the code base

A couple of general tips if you want to modify treemacs beyond its builtin configuration options.

• If you want to get a feel for the codebase look to the functions treemacs and treemacs--push-button, they're general entry points for a large part of treemacs' functionality.
• Treemacs expects paths to be formatted the way f.el formats path - without the final slash. The only exception is the value of default-directory in the treemacs buffer so the correct directory is selected when creating files through treemacs.
• Each line in treemacs is a button, each button has a set of useful properties.
  • abs-path the absolute path if the button is a file
  • depth number indicating how deeply nested the button is, used for indentation
  • parent the button's parent button, if any
  • next/prev-node the button's same level neighbours
  • index the button's part of the tags index, if it's a tags section
  • state indicates the type of the button. Can be one of the following: dir-node-open, dir-node-closed, file-node-open, file-node-closed, tag-node-open, tag-node-closed, tag-node
• Reading button properties can be dangerous, since it only works when the call to button-get or a similar function only works when called from inside the same buffer the button is positioned in. In this case use either treemacs--safe-button-get or treemacs--with-button-buffer.
• If you want to define a general function to consistently handle various button types the way treemacs-visit-node-* do you can use the treemacs--execute-button-action. It'll handle button state matching, error handling and window switching, you need only supply the pieces. Above warning about reading button properties in the correct buffer applies here, since the macro needs to switch to the given window before running its code.
• To add more icons look to treemacs--create-icons and treemacs--setup-icon. You need only put a png file in the icons folder, the macro will do the rest.