README.org

org-treeusage.el

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.

Installation

Install from MELPA or using use-package:

(use-package org-treeusage
  :bind ("C-c d" . org-treeusage-mode)
  :custom (org-treescope-overlay-header nil))

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.

'(((-9 .  1)  . ▏)
  (( 2 . 10)  . ▎)
  ((11 . 20)  . ▋)
  ((21 . 30)  . █)
  ((31 . 40)  . █▋)
  ((41 . 50)  . ██)
  ((51 . 60)  . ██▋)
  ((61 . 70)  . ███)
  ((71 . 80)  . ███▋)
  ((81 . 90)  . ████)
  ((91 . 110) . ████▋))

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.

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.

'((bardiffpercname . "%1$-5s |%3$-5d|%2$5.1f%%|%4$s")
  (bardiffperc . "%1$-5s |%3$-5d|%2$5.1f%%")
  (bardiffname . "%1$s%3$-5d|%4$s")
  (bardiff . "%1$s%3$d")
  (barname . "%1$-5s |%4$s")
  (bar . "%1$-5s")
  (percname . "%2$5.1f%%|%4$s")
  (perc . "%2$5.1f%%")
  (diffname . "%3$d|%4$s")
  (diff . "%3$d"))

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:

1. A string representing the percentage band of headline (as explained in the previous subsection).
2. A float representing the actual current percentage of the headline.
3. An integer showing the number of lines or characters in the headline content.
4. A string with the actual name of the headline.

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