org-treeusage.el

org-treeusage.el copied to clipboard

#+TITLE: org-treeusage.el

*** This repo has migrated to GitLab https://gitlab.com/mtekman/org-treeusage.el ****** (The copy here is archived. Please see the above link for the latest developments)

#+HTML:

#+HTML:

This library provides a minor mode for peeking at the line or character usage of each heading in an org-mode file with respect to the parent heading, allowing users with large org files to see the distribution of heading content and make informed decisions on where to prune, refile, or archive.

#+HTML:

** Installation

Install from MELPA or using =use-package=:

#+begin_src elisp (use-package org-treeusage :bind ("C-c d" . org-treeusage-mode) :custom ;; Below two settings recreate the above image ((org-treescope-overlay-header nil) (org-treeusage-overlay-usecolorbands nil))) #+end_src

** Usage

Enable =org-treeusage-mode= and press either =COMMA= / =DOT= to cycle either backwards / forwards between the different the line formats (see below).

By default the mode measures percentage of content by the number of lines in each headline, but this can be toggled to measure number of characters by pressing =l=.

/The differences between measuring line or character are not drastic, but could be useful./

** Customisation

***** Header with Bindings

By default a header with binding information is given when the mode is activated (not pictured in live demo), but this can be easily disabled by setting =org-treeusage-overlay-header= to nil (as in the installation example).

***** Percentage Bands

The percentage of the contributing content of the current heading divided by the parent is represented by a symbol that maps to one of the percentage bands given by =org-treeusage-overlay-percentlevels=.

#+begin_src elisp ;; (min-% . max-%) . (%-symbol . face) '(((-9 . 1) . (▏ . magit-blame-dimmed)) (( 2 . 10) . (▎ . magit-blame-dimmed)) ((11 . 20) . (▋ . ibuffer-locked-buffer)) ((21 . 30) . (█ . ibuffer-locked-buffer)) ((31 . 40) . (█▋ . magit-reflog-rebase)) ((41 . 50) . (██ . magit-reflog-rebase)) ((51 . 60) . (██▋ . magit-signature-revoked)) ((61 . 70) . (███ . magit-signature-error)) ((71 . 80) . (███▋ . magit-signature-drop)) ((81 . 90) . (████ . magit-signature-bad)) ((91 . 110) . (████▋ . magit-signature-bad))) #+end_src

By default there 11 bands each assigned vertical bar symbols that increase with the percentage band, but there could ultimately be any number of bands representing any symbols the user desires. The bands should /ideally/ not overlap, but it is not a strict requirement, where the first matching band is returned.

By default, the entire heading is coloured by the faces given for the corresponding percentage band, but this can be disabled to fallback onto the org-heading-level faces by setting =org-treeusage-overlay-usecolorbands= to =nil=.

***** Line Formats

There are 10 different line formats provided in the =org-treeusage-cycle-format= variable, each providing a different sub-selection of titles and metrics to show to the user -- usually a different permutation of four different variables manipulated in format control strings, to represent the percentage /bar/, the percentage amount /perc/, the absolute content amount /diff/, and the headline name /name/.

#+begin_src elisp '((barname . "%1$-5s |%7$s") (bardiffname . "%1$s%3$-5d|%7$s") (barpercdiffname . "%1$-5s |%2$5.1f%%|%3$-5d|%7$s") (percname . "%2$5.1f%%|%7$s") (diffname . "%3$d|%7$s") (barpercdiffallname . "%1$-5s |%2$5.1f%%|l%4$-3d w%5$-4d c%6$-5d|%7$s") (bardiffperc . "%1$-5s |%3$d|%2$5.1f%%") (bardiff . "%1$s%3$d") (bar . "%1$-5s") (perc . "%2$5.1f%%") (diff . "%3$d")) #+end_src

The names are descriptive but arbitrary, and users can append their own to the =org-treeusage-cycle-format= variable. The value of each pair describes 6 position arguments:

#+begin_src conf 1. A string representing the percentage band for the current diff type. 2. A float showing the current percentage for current diff type. 3. An integer showing the absolute diff type amount. 4,5,6. An integer showing the current values for lines, words, chars. 7. A string with the title of the headline." #+end_src

Please consult the in-built help =C-h f RET format= for more information on how to represent these values.

** Similar Projects

• [[https://github.com/novoid/org-du/][org-du]] provides an interactive graphical representation of an org-file whilst being independent of emacs.

** Changelog

*** 0.4

• Added caching (massive performance increase!)
• Fixed dodgy header line and mode line

*** 0.3

• Added =org-treeusage-overlay-colorbands= custom setting to colourise percentage bands.

*** 0.2

• Initial release