Configure template - keep transit heading level consistent!

treefactor-throw and treefactor-up create a file when refiling a heading to a directory that doesn't already have one. They insert a template into the new file. You can modify this template via the Customization option "Treefactor Inbox File Header".

The default value assumes that you will always use level-four headings for blind inter-file refiling. It creates a level-three heading to act as a parent for these level-four headings.

You should pick one heading level for blind inter-file heading refiling, and stick to it. Otherwise you may cause unintended parent-child relationships. Child-heading folding may cause you to overlook such mistakes, resulting in further disorganization.

Unintended folding is a general problem for Emacs outline-manipulation commands. If anticipated, it is easily avoided. Otherwise, one can wind up mistakenly deleting important information because it was a folded descendant of an unwanted heading. Like any power tool, an outline permits more powerful mistakes. Always use a git repo to ensure that mistakes are recoverable.

Aliasing the "treefactor" prefix

An alias creates an additional name for a command. Treefactor commands are prefixed with "treefactor". This prefix is 10 characters long, which can be inconvenient to type repeatedly.

Treefactor lets you easily alias a shorter prefix. Customize "Treefactor use alias prefixes" to t. The default for the first alias is "tro", which is a phonetic misspelling of "throw".

Do not set an alias to "treefactor", as that will cause a loop when the package is loaded.

By binding the following commands to convenient keychords, you can refile without thinking about it:

  (global-set-key (kbd "H-f") 'treefactor-throw)
  (global-set-key (kbd "H-g") 'treefactor-up)
  (global-set-key (kbd "C-c k") 'treefactor-delete-this-buffer-and-file)
  (global-set-key (kbd "C-c l") 'treefactor-org-store-link-fold-drawer)
  (global-set-key (kbd "H-a") 'other-window)
  (global-set-key (kbd "H-w") 'outline-up-heading)
  (global-set-key (kbd "H-e") 'outline-previous-visible-heading)
  (global-set-key (kbd "H-r") 'outline-next-visible-heading)
  (global-set-key (kbd "H-d") 'org-narrow-to-subtree)
  (global-set-key (kbd "H-s") 'widen)
  (global-set-key (kbd "H-1") 'spacemacs/toggle-maximize-buffer)
  (global-set-key (kbd "H-2") 'delete-window)
  (global-set-key (kbd "H-3") 'split-window-right)
  (global-set-key (kbd "s-i") 'ido-dired)
  (global-set-key (kbd "H-b") 'clone-indirect-buffer-other-window)
  (global-set-key (kbd "H-v") 'treefactor-org-refactor-heading)

I use a Microsoft Natural Ergonomic Keyboard. I set the Appkey to Hyper and the Winkey to Super.

Org search scope

Treefactor permits rapid rearrangement of files and directories. This violates Org's assumption that files and directories will remain mostly unchanged during an Emacs session. Org doesn't notice path changes within its search scope. This is dangerous when relying on Org searches.

The solution is to refresh Org's knowledge of the paths within its search scope. Normally a refresh only happens when Emacs starts. Treefactor provides commands to refresh at will.

First, tell Treefactor which directories to search. Customize the variables treefactor-org-agenda-dir and treefactor-org-id-extra-dir. The former contains Org agenda files. The latter contains Org files to be searched for IDs, besides the agenda files.

Why have two different directories for searches? Because agenda searches are much slower than ID searches. Store sparse agenda headings in the agenda directory, and bulk text in the ID directory.

ID searches are fast because link paths are cached. Run a nightly ID search to keep the ID registry updated, for lagless ID links. To refresh the ID registry, search for a fake link. Making a fake link is easy. Just make a real link, then replace the real ID with a fake one, like so:

[[id:D0F1C51F-BD4A-4278-8F46-ACBD6A35B1B3][real link]]
[[id:fake][fake link]]