Org Capturing Introduction

The org-capture function is quite useful for some workflows, however, the standard documentation for it quickly jumps into template writing without really explaining its use case. The following essay attempts to be a gentle introduction to org-capture. I will assume you are familiar with both Org and Emacs, but don’t know anything about org-capture.

The org-capture feature is global, meaning that it may be called anywhere in Emacs– whether you are editing an org file or reading email. Calling it displays a buffer, allowing you to jot some notes. When dismissed, the notes are saved in a specific location based on the type of note. Hrm…examples are in order:

  1. Wile reading my mail, I remember some items to buy at the store, I start org-capture (specifying a task) and store a TODO header entitled Shopping with a list in my task file.
  2. While reading some code, I notice one of my team members clarified the originally terse README with helpful examples. To remind myself to publicly thank her at the next Sprint Retrospective, I launch org-capture (specifying a “Sprint Goodness”), and jot down the note, knowing that at the Sprint Retro, I can retrieve the file containing my Sprint notes.
  3. While running eshell on a remote server, I notice our Rakefile has a spelling mistake. Since I should fix that (just not now), I quickly start org-capture (specifying a “Bug”), and jot the details for a bug fix at the end of the day.
  4. While analyzing a new code base, I select each interesting function, and call org-capture to copy it (maybe with some thoughts) to n “Project File”. Each code snippet is properly formatted (in a literate programming style) with a link back to the original code file. By the time, I have encountered something questionable, I can export my “Project File” and mail it to collegues with questions.

The list of these destinations, and types of notes, can be a long as you want. Here is a screenshot of Emacs running on my work computer where each type of note (with its destination) is associated with a single key:

capturing-intro-02.png

Hopefully, this gives you some possibilities for how org-capture can be used.

Getting Started

Let’s try it. The org-capture function, being a globally called function (and not just called within an Org file), should have some shortcut key. The docs suggest C-c c (in Spacemacs, this is SPC a o c), however, you can just issue a good ol’ fashioned, M-x org-capture:

capturing-intro-01.png

Hit t to create a task, and an org-mode buffer appears with a TODO header:

capturing-intro-03.png

Enter a task as if it were part of a greater org-mode file (because it is):

capturing-intro-04.png

Hit C-c C-c to save, and Emacs mentions that the task was stored in ~/.notes. Let’s open it:

capturing-intro-05.png

Notice that it is exactly as we typed it, just under a heading of Tasks. Well, there you have it, you have just created a nice Task List system.

Default Tasks

As you know, Emacs is synonymous for possibilities, so let’s begin to customize this feature by entering this code in the *scratch* buffer: 

(setq org-default-notes-file "~/Dropbox/notes/tasks.org")

This changes the default file location for our tasks from ~/.notes to an entry in our Dropbox folder. Why there? Install a copy of Orgzly on your phone, and point it to the notes folder in your Dropbox account, and you’ll find your new task shown there.

I can’t describe Orgzly here, and the documentation, while complete, isn’t a tutorial. I would suggest having it create a default example file, and playing around with it. Shouldn’t take long before your computer and phone are singing a song of todos…

Obviously having a single file where you throw all your TODOs will quickly become unwieldy. I use org-archive to essentially backup closed TODOs.

Other Destinations

Each Org Capture Template consists of at least three parts:

  • A key binding– to select a particular template
  • A destination– a file, and some section in that file, like a heading, sub-heading, list item, etc.
  • A formatting template– allowing you to fill in the details instead of typing everything. In the example above, this included the sub-header (with the two asterisks), the TODO text, etc.

If you wanted to divide tasks into personal and work. We will let the tasks.org file (defined above) contain our personal stuff, and work-related tasks will go into work.org: 

(add-to-list 'org-capture-templates
             '("w" "Work-related Task"  entry
               (file "~/Dropbox/notes/work.org")
               "* TODO %?" :empty-lines 1))

Run org-capture, and we now have our new w template (but we lost our default). Type q and let’s configure org-capture to have both: 

(add-to-list 'org-capture-templates
             '("t" "Personal Task"  entry
               (file org-default-notes-file)
               "* TODO %?" :empty-lines 1))

Use either template to fill both files and then edit them to see the results.

You may find yourself placing bugs, feature requests, stories, and meeting notes in your work.org file. At the end of the day, you could deal with the day’s clutter by moving tasks that could not be trivially completed into other, dedicated project files. This is why Sacha mentions the org-refile function in combination with org-capture.

Summary

In this essay, we talked about the workflows associated with org-capture, as well as how to start creating simple templates. At this point, I hope you have enough context to dive into the org-template documentation to create a beautiful workflow.

Next, you might enjoy my following essay on capturing content in Emacs, or see my org-capture templates. If you own a Mac, you might try a capturing interface using a Mac program called Alfred. See the subsection on my Keyboard.io review.

Let me know if you do anything interesting with capturing content into org files.