Usage

To begin with I wanted to break up my items into categories, one category per file. After some waffling, the categories I settled upon for work were:

• devel.org: Every item that is going to involve me personally writing code.
• reviews.org: Coding work owned by other developers, that I need to review or pair with them on.
• watching.org: Items that I want to keep an eye on, but that aren't yet ready to be worked on or prioritized
• professional.org: Professional development, giving talks, mentoring, or other things of that nature.
• other.org: Procedural things that don't comfortably fit in any of the other categories, e.g. talking to IT about problems with one of my accounts.

While I could have just cut and pasted items from my original todo.org file into their respective new files, I wanted something a bit more streamlined. It seemed like the org-refile command (C-c C-w) fit what I wanted, but by default it would only target existing headlines within the same file. I couldn't target other files and I couldn't keep items at the same headline level without doing some extra work.

It turns out that there is a pair of settings (as noted below in the Settings section) that allows you to both target all of your org files and build up a slash-separated target path that includes the filename. This can be just the file name if you want to move the subtree to the top level of the target file, which is what I did to move items out of todo.org into their desired category files. You can even target the same file it already lives in, which will move it to the bottom of the file. I started using that particular feature this week to move items that I had taken some action on but wasn't yet ready to archive to the bottom of the file, in order to keep things that I should look at next towards the top. Finally, you can target some headline if you want the subtree to become a child of that headline. In my case, I used this for a closely related issue that I felt should be addressed in the same pull request as another.

Examples:

• From todo.org, target devel.org/: Moves the subtree to the bottom of devel.org.
• From devel.org, target devel.org/: Moves the subtree to the bottom of the file.
• From devel.org, target reviews.org/Some top-level headline/: Moves the subtree to become a child subtree below this headline.

In all of these cases, tab completion works and TAB can be pressed twice to pull up a menu of potential options.

I should note however, that the files have to already exist in order to be a valid target for the refile command. So to get the new files started, I used Emacs' normal find-file command (C-x C-f) and then saved it empty.

Finally, this week I reached the point where some items had all of their actions set to DONE, and I was reasonably sure I wasn't going to need to revisit them. To deal with these, I used the org-archive-subtree command (C-c C-x C-s, though possibly I should have been using C-c C-x C-a instead?). This moves the subtree to an archive file, creating it if it does not exist, based on whatever pattern is in the settings. I haven't changed this setting and probably won't care for a while, so this has been the default, e.g. items from devel.org get sent to devel.org_archive. I could see those files eventually becoming large, though, so moving them occasionally or making the pattern include parts of the date might be nice.

Settings

• org-refile-targets: By default, org-mode only allows refiling to the current agenda file. Changing this to make use of the org-agenda-files setting allowed me to target any of my other org files, which works well in conjunction with the next setting.
• org-refile-use-outline-path: This allowed me to include the filename as part of the path to the location I want the subtree to be moved to.

After these changes, the org-mode section in my .emacs file looks like this:

(global-set-key (kbd "C-c l") #'org-store-link)
(global-set-key (kbd "C-c a") #'org-agenda)
(global-set-key (kbd "C-c c") #'org-capture)

(setq org-log-done 'time
      org-agenda-files   (list "~/org/")
      org-refile-targets '((org-agenda-files :maxlevel . 5))
      org-refile-use-outline-path 'file
)

Key Bindings Learned

• C-c C-w: Refile the current subtree to a file or as a child of some other subtree.
• C-c C-x C-s: Archive the current subtree into an archive file. I'm not clear what the difference is between this and C-c C-x C-a (archive subtree using the default command). I should definitely look into that. The manual also shows a "short" command, C-c $. I should try that out, but haven't done so yet.

Next Steps

This week I started to want the ability to set deadlines and scheduled events, so that will be what I tackle next week.