Org-mode, The Ultimate Organization Tool

A great lot of this was taken from http://doc.norang.ca/org-mode.html, to which I owe almost all of
the agenda configuration. The capture stuff and regular org settings are mine.

Also, in order to export nicely colored HTML of source code, we need htmlize. Otherwise the source
code is bland in HTML output. I also install org-plus-contrib and immediately require org, because
I know I'm going to use it. Yes this does slow down startup a bit, but I think it's worth it.

First, the hook that gets run every time org-mode is started, to turn on certain modes. I increase
the column width, turn on auto-filling, spellcheck, snippet expansion, and abbreviations, and then
set up some custom keybindings that should take effect in every org mode buffer.

Project Task States

I use a lazy project definition. I don't like to bother with manually stating 'this is a project'
and 'that is not a project'. For me a project definition is really simple. If a task has subtasks
with a todo keyword then it's a project. That's it.

Projects can be defined at any level - just create a task with a todo state keyword that has at
least one subtask also with a todo state keyword and you have a project. Projects use the same todo
keywords as regular tasks. One subtask of a project needs to be marked NEXT so the project is not
on the stuck projects list.

Meetings

Meetings are special. They are created in a done state by a capture task. I use the MEETING capture
template when someone interrupts what I'm doing with a question or discussion. I clock the amount of
time spent with whomever it is and record some notes of what was discussed (either during or after
the meeting) depending on content, length, and complexity of the discussion.

The time of the meeting is recorded for as long as the capture task is active. If I need to look up
other details and want to close the capture task early I can just C-c C-c to close the capture
task (stopping the clock) and then f9 SPC to resume the clock in the meeting task while I do other
things.

title Meeting Task State
[*] -> MEETING
MEETING -> [*]

Fast Todo Selection

Fast todo selection allows changing from any task todo state to any other state directly by
selecting the appropriate key from the fast todo selection key menu. This is a great feature!

(setq org-use-fast-todo-selection t)

Changing a task state is done with C-c C-t KEY

where KEY is the appropriate fast todo state selection key as defined in org-todo-keywords.

The setting

(setq org-treat-S-cursor-todo-selection-as-state-change nil)

allows changing todo states with S-left and S-right skipping all of the normal processing when
entering or leaving a todo state. This cycles through the todo states but skips setting timestamps
and entering notes which is very convenient when all you want to do is fix up the status of an
entry.

Todo state triggers

I have a few triggers that automatically assign tags to tasks based on state changes. If a task
moves to CANCELLED state then it gets a CANCELLED tag. Moving a CANCELLED task back to TODO
removes the CANCELLED tag. These are used for filtering tasks in agenda views.

Adding tasks with org capture

To add new tasks efficiently I use a minimal number of capture
templates. I used to have lots of capture templates, one for each
org-file. I'd start org-capture with C-c c and then pick a template
that filed the task under * Tasks in the appropriate file.

I found I still needed to refile these capture tasks again to the
correct location within the org-file so all of these different capture
templates weren't really helping at all. Since then I've changed my
workflow to use a minimal number of capture templates – I create the
new task quickly and refile it once. This also saves me from
maintaining my org-capture templates when I add a new org file.

Capture Templates

When a new task needs to be added I categorize it into one of a few
things:

Capture mode now handles automatically clocking in and out of a capture task. This all works out of
the box now without special hooks. When I start a capture mode task the task is clocked in as
specified by :clock-in t and when the task is filed with C-c C-c the clock resumes on the
original clocking task.

The quick clocking in and out of capture mode tasks (often it takes less than a minute to capture
some new task details) can leave empty clock drawers in my tasks which aren't really useful. Since I
remove clocking lines with 0:00 length I end up with a clock drawer like this:

* TODO New Capture Task :LOGBOOK: :END:[2010-05-08 Sat 13:53]

I have the following setup to remove these empty LOGBOOK drawers if they occur.

Separate files for Capture Tasks

I have a single org file which is the target for my capture templates.

I store notes, tasks, phone calls, and org-protocol tasks in refile.org. I used to use multiple
files but found that didn't really have any advantage over a single file.

Normally this file is empty except for a single line at the top which creates a REFILE tag for
anything in the file.

The file has a single permanent line at the top like this

#+FILETAGS: REFILE

Capture Tasks is about being Fast

Okay I'm in the middle of something and oh yeah - I have to remember to do that. I don't stop what
I'm doing. I'm probably clocking a project I'm working on and I don't want to lose my focus on that
but I can't afford to forget this little thing that just came up.

So what do I do? Hit C-c c to start capture mode and select t since it's a new task and I get a
buffer like this:

Enter the details of the TODO item and C-c C-c to file it away in refile.org and go right back to
what I'm really working on secure in the knowledge that that item isn't going to get lost and I
don't have to think about it anymore at all now.

The amount of time I spend entering the captured note is clocked. The capture templates are set to
automatically clock in and out of the capture task. This is great for interruptions and telephone
calls too.

Refiling Tasks

Refiling tasks is easy. After collecting a bunch of new tasks in my refile.org file using capture
mode I need to move these to the correct org file and topic. All of my active org-files are in my
org-agenda-files variable and contribute to the agenda.

I collect capture tasks in refile.org for up to a week. These now stand out daily on my block agenda
and I usually refile them during the day. I like to keep my refile task list empty.

Refile Setup

To refile tasks in org you need to tell it where you want to refile things.

In my setup I let any file in org-agenda-files and the current file contribute to the list of
valid refile targets.

I use Helm to list the refile targets. Now when I want to refile something I do C-c C-w to start
the refile process, then type something to get some matching targets, then

I now exclude DONE state tasks as valid refile targets. This helps to keep the refile target list
to a reasonable size.

Task Refiling

Tasks to refile are in their own section of the block agenda. To find tasks to refile I run my
agenda view with M-t a and scroll down to second section of the block agenda: Tasks to Refile.
This view shows all tasks (even ones marked in a done state).

Bulk refiling in the agenda works very well for multiple tasks going to the same place. Just mark
the tasks with m and then B r to refile all of them to a new location. Occasionally I'll also
refile tasks as subtasks of the current clocking task using C-2 C-c C-w from the refile.org
file.

Refiling all of my tasks tends to take less than a minute so I normally do this a couple of times a
day.

Refiling Notes

I keep a * Notes headline in most of my org-mode files. Notes have a NOTE tag which is created
by the capture template for notes. This allows finding notes across multiple files easily using the
agenda search functions.

Notes created by capture tasks go first to refile.org and are later refiled to the appropriate
project file. Some notes that are project related get filed to the appropriate project instead of
under the catchall * NOTES task. Generally these types of notes are specific to the project and
not generally useful – so removing them from the notes list when the project is archived makes
sense.

Refiling Phone Calls and Meetings

Meetings are handled using capture mode. I time my calls and meetings using the capture mode
template settings to clock in and out the capture task while the phone call or meeting is in
progress.

Meeting tasks collect in refile.org and are later refiled to the appropriate location.

Custom Agenda Views

I now have one block agenda view that has everything on it. I also keep separate single view agenda
commands for use on slower machines - since it takes prohibitively long to generate my block agenda.
I'm striving to simplify my layout with everything at my fingertips in a single agenda on my
workstation which is where I spend the bulk of my time.

Custom agenda views are used for:

Single block agenda shows the following

overview of today

Finding tasks to be refiled

Finding stuck projects

Finding NEXT tasks to work on

Show all related tasks

Reviewing projects

Finding tasks waiting on something

Findings tasks to be archived

Finding notes

If I want just today's calendar view then F12 a is still faster than generating the block agenda -
especially if I want to view a week or month's worth of information, or check my clocking data. In
that case the extra detail on the block agenda view is never really needed and I don't want to spend
time waiting for it to be generated.

After selecting a project (with P on any task in the agenda) the block agenda changes to show the
project and any subprojects in the Projects section. Tasks show project-related tasks that are
hidden when not narrowed to a project. This makes it easy to focus on the task at hand.

I generally work top-down on the agenda. Things with deadlines and scheduled dates (planned to work
on today or earlier) show up in the agenda at the top.

My day goes generally like this:

Clock in (usually on the Meta task)

Look at the agenda and make a mental note of anything important to deal with today

Read email and news (clocked in to "Meta")

create notes, and tasks for things that need responses with org-capture

Check refile tasks and respond to emails

Look at my agenda and work on important tasks for today

Clock it in

Work on it until it is DONE or it gets interrupted

Work on tasks

Clock out for lunch and clock back in after lunch

work on more tasks

Refile tasks to empty the list

Tag tasks to be refiled with m collecting all tasks for the same target

What should I work on next?

Start with deadlines and tasks scheduled today or earlier from the daily agenda view. Then move on
to tasks in the Next Tasks list in the block agenda view. I tend to schedule current projects to
'today' when I start work on them and they sit on my daily agenda reminding me that they need to be
completed. I normally only schedule one or two projects to the daily agenda and unschedule things
that are no longer important and don't deserve my attention today.

When I look for a new task to work on I generally hit F12 SPC to get
the block agenda and follow this order:

Pick something off today's agenda

deadline for today (do this first - it's not late yet)

deadline in the past (it's already late)

a scheduled task for today (it's supposed to be done today)

a scheduled task that is still on the agenda

deadline that is coming up soon

pick a NEXT task

If you run out of items to work on look for a NEXT task in the current context
pick a task from the Tasks list of the current project.

Why keep it all on the NEXT list?

I've moved to a more GTD way of doing things. Now I just use a NEXT list. Only projects get tasks
with NEXT keywords since stuck projects initiate the need for marking or creating NEXT tasks. A
NEXT task is something that is available to work on now, it is the next logical step in some
project.

Having an agenda view that shows NEXT tasks makes it easy to pick the thing to clock. The NEXT
list is basically 'what is current' - any task that moves a project forward. I want to find the
thing to work on as fast as I can and actually do work on it - not spend time hunting through my org
files for the task that needs to be clocked-in.

To drop a task off the NEXT list simply move it back to the TODO state.

TODO Reading Email, RSS, Twitter and IRC

When reading email, RSS, and conversations on IRC I just let the default task (normally * Meta)
clock the time I spend on these tasks. To read email I go to Mu4e and read everything in my inboxes.
If there are emails that require a response I use org-capture to create a new task with a heading of
'Respond to <user>' for each one. This automatically links to the email in the task and makes it
easy to find later. Some emails are quick to respond to and some take research and a significant
amount of time to complete. I clock each one in it's own task just in case I need that clocked time
later. The capture template for Repond To tasks is now scheduled for today so I can refile the task
to the appropriate org file without losing the task for a week.

Next, I go to my newly created tasks to be refiled from the agenda with M-t a and clock in an
email task and deal with it. Repeat this until all of the 'Respond to <user>' tasks are marked
DONE.

Filtering

So many tasks, so little time. I have lots of tasks at any given time. There is so much stuff to
look at it can be daunting. This is where agenda filtering saves the day.

It's 11:53AM and I'm in work mode just before lunch. I don't want to see tasks that are not work
related right now. I also don't want to work on a big project just before lunch… so I need to find
small tasks that I can knock off the list.

How do we do this? Get a list of NEXT tasks from the block agenda and then narrow it down with
filtering. Tasks are ordered in the NEXT agenda view by estimated effort so the short tasks are
first – just start at the top and work your way down. I can limit the displayed agenda tasks to
those estimates of 10 minutes or less with / + 1 and I can pick something that fits the minutes I
have left before I take off for lunch.

Automatically removing context based tasks with / RET

/ RET in the agenda is really useful. This awesome feature was added to org-mode by John Wiegley.
It removes tasks automatically by filtering based on a user-provided function.

At work I have projects I'm working on which are assigned by my manager. Sometimes priorities
changes and projects are delayed to sometime in the future. This means I need to stop working on
these immediately. I put the project task on HOLD and work on something else. The / RET filter
removes HOLD tasks and subtasks (because of tag inheritance).

I have the following setup to allow / RET to filter tasks based on the description above.

This lets me filter tasks with just / RET on the agenda which removes tasks I'm not supposed to be
working on now from the list of returned results.

This helps to keep my agenda clutter-free.

Time Clocking

Okay, I admit it. I'm a clocking fanatic.

I clock everything at work. Org-mode makes this really easy. I'd rather clock too much stuff than
not enough so I find it's easier to get in the habit of clocking everything.

This makes it possible to look back at the day and see where I'm spending too much time, or not
enough time on specific projects. This also helps a lot when you need to estimate how long something
is going to take to do – you can use your clocking data from similar tasks to help tune your
estimates so they are more accurate.

Without clocking data it's hard to tell how long something took to do after the fact.

My clocking setup basically works like this:

Clock in to the "Meta" task

This clocks in a predefined task by org-id that is the default task to clock in whenever the
clock normally stops

Clock in tasks normally, and let moving to a DONE state clock out

clocking out automatically clocks time on a parent task or moves back to the predefined default
task if no parent exists.

Continue clocking whatever tasks you work on

Clock out (stop the clock)

I'm free to change the default task multiple times during the day but with the clock moving up the
project tree on clock out I no longer need to do this. I simply have a single task that gets clocked
in when I punch-in.

If I punch-in with a prefix on a task in Project X then that task automatically becomes the
default task and all clocked time goes on that project until I either punch out or punch in some
other task.

If I am working on some task, then I simply clock in on the task. Clocking out moves the clock up to
a parent task with a todo keyword (if any) which keeps the clock time in the same subtree. If there
is no parent task with a todo keyword then the clock moves back to the default clocking task until I
punch out or clock in some other task. When an interruption occurs I start a capture task which
keeps clocked time on the interruption task until I close it with C-c C-c.

Pick 'TODO Some miscellaneous task' to work on next and clock that in with I The clock is now
on 'TODO Some miscellaneous task'

I complete that task and mark it done with C-c C-t d

This stops the clock and moves it back to the Organization task.

Now I want to work on Project A so I clock in Task 1

I work on Task 1 and mark it DONE. This clocks out Task 1 and moves the clock to Project A.
Now I work on Task 2 and clock that in.

The entire time I'm working on and clocking some subtask of Project A all of the clock time in the
interval is applied somewhere to the Project A tree. When I eventually mark Project A done then
the clock will move back to the default organization task.

Clock Setup

To get started we need to punch in which clocks in the default task and keeps the clock running.
This is now simply a matter of punching in the clock with F9 I. You can do this anywhere. Clocking
out will now clock in the parent task (if there is one with a todo keyword) or clock in the default
task if not parent exists.

Keeping the clock running when moving a subtask to a DONE state means clocking continues to apply
to the project task. I can pick the next task from the parent and clock that in without losing a
minute or two while I'm deciding what to work on next.

I keep clock times, state changes, and other notes in the :LOGBOOK: drawer.

I have the following org-mode settings for clocking:

;; Resume clocking task when emacs is restarted;; (org-clock-persistence-insinuate);; Show lot of clocking history so it's easy to pick items off the `C-c I` list(setq org-clock-history-length 23);; Resume clocking task on clock-in if the clock is open(setq org-clock-in-resume t);; Change tasks to NEXT when clocking in(setq org-clock-in-switch-to-state 'bh/clock-in-to-next);; Save clock data and state changes and notes in the LOGBOOK drawer(setq org-clock-into-drawer t);; Sometimes I change tasks I'm clocking quickly - this removes clocked tasks;; with 0:00 duration(setq org-clock-out-remove-zero-time-clocks t);; Clock out when moving task to a done state(setq org-clock-out-when-done t);; Save the running clock and all clock history when exiting Emacs, load it on startup;; (setq org-clock-persist t);; Do not prompt to resume an active clock;; (setq org-clock-persist-query-resume nil);; Enable auto clock resolution for finding open clocks(setq org-clock-auto-clock-resolution (quote when-no-clock-is-running));; Include current clocking task in clock reports(setq org-clock-report-include-clocking-task t);; don't use pretty things for the clocktable(setq org-pretty-entities nil);; If idle for more than 15 minutes, resolve the things by asking what to do;; with the clock time(setq org-clock-idle-time 15)(defuneos/org-clock-in()(interactive)(org-clock-in '(4)))(global-set-key (kbd "<f11>")#'eos/org-clock-in)(global-set-key (kbd "C-c I")#'eos/org-clock-in)(global-set-key (kbd "<f12>")#'org-clock-out)(global-set-key (kbd "C-c O")#'org-clock-out)(setq bh/keep-clock-running nil)(defunbh/clock-in-to-next(kw)"Switch a task from TODO to NEXT when clocking in.Skips capture tasks, projects, and subprojects. Switch projectsand subprojects from NEXT back to TODO"(when(not (and(boundp 'org-capture-mode) org-capture-mode))(cond((and(member (org-get-todo-state)(list "TODO"))(bh/is-task-p))"NEXT")((and(member (org-get-todo-state)(list "NEXT"))(bh/is-project-p))"TODO"))))(defunbh/find-project-task()"Move point to the parent (project) task if any"(save-restriction(widen)(let((parent-task (save-excursion(org-back-to-heading 'invisible-ok)(point))))(while(org-up-heading-safe)(when(member (nth 2(org-heading-components)) org-todo-keywords-1)(setq parent-task (point))))(goto-char parent-task)
parent-task)))(defunbh/punch-in(arg)"Start continuous clocking and set the default task to theselected task. If no task is selected set the Organization taskas the default task."(interactive"p")(setq bh/keep-clock-running t)(if(equal major-mode 'org-agenda-mode);;;; We're in the agenda;;(let*((marker (org-get-at-bol 'org-hd-marker))(tags (org-with-point-at marker (org-get-tags-at))))(if(and(eq arg 4) tags)(org-agenda-clock-in '(16))(bh/clock-in-organization-task-as-default)));;;; We are not in the agenda;;(save-restriction(widen); Find the tags on the current task(if(and(equal major-mode 'org-mode)(not (org-before-first-heading-p))(eq arg 4))(org-clock-in '(16))(bh/clock-in-organization-task-as-default)))))(defunbh/punch-out()(interactive)(setq bh/keep-clock-running nil)(when(org-clock-is-active)(org-clock-out))(org-agenda-remove-restriction-lock))(defunbh/clock-in-default-task()(save-excursion(org-with-point-at org-clock-default-task
(org-clock-in))))(defunbh/clock-in-parent-task()"Move point to the parent (project) task if any and clock in"(let((parent-task))(save-excursion(save-restriction(widen)(while(and(not parent-task)(org-up-heading-safe))(when(member (nth 2(org-heading-components)) org-todo-keywords-1)(setq parent-task (point))))(if parent-task
(org-with-point-at parent-task
(org-clock-in))(when bh/keep-clock-running
(bh/clock-in-default-task)))))))(defvarbh/organization-task-id"default-task-id")(defunbh/clock-in-organization-task-as-default()(interactive)(org-with-point-at(org-id-find bh/organization-task-id 'marker)(org-clock-in '(16))))(defunbh/clock-out-maybe()(when(and bh/keep-clock-running
(not org-clock-clocking-in)(marker-buffer org-clock-default-task)(not org-clock-resolving-clocks-due-to-idleness))(bh/clock-in-parent-task)))(add-hook 'org-clock-out-hook'bh/clock-out-maybe'append)

I used to clock in tasks by ID using the following function but with the new punch-in and punch-out
I don't need these as much anymore. f9-SPC calls bh/clock-in-last-task which switches the clock
back to the previously clocked task.

(require'org-id)(defunbh/clock-in-task-by-id(id)"Clock in a task by id"(org-with-point-at(org-id-find id 'marker)(org-clock-in nil)))(defunbh/clock-in-last-task(arg)"Clock in the interrupted task if there is oneSkip the default task and get the next one.A prefix arg forces clock in of the default task."(interactive"p")(let((clock-in-to-task
(cond((eq arg 4) org-clock-default-task)((and(org-clock-is-active)(equal org-clock-default-task (cadr org-clock-history)))(caddr org-clock-history))((org-clock-is-active)(cadr org-clock-history))((equal org-clock-default-task (car org-clock-history))(cadr org-clock-history))(t (car org-clock-history)))))(widen)(org-with-point-at clock-in-to-task
(org-clock-in nil))))

Clocking in

When I start or continue working on a task I clock it in with any of the following:

C-c C-x C-i

I in the agenda

I speed key on the first character of the heading line

f9 I while on the task in the agenda

f9 I while in the task in an org file

Setting a default clock task

I have a default ** Meta task in my todo.org file that I tend to put miscellaneous clock time on.
This is the task I clock in on when I punch in at the start of my work day with C-c I. While
reorganizing my org-files, reading email, clearing my inbox, and doing other planning work that
isn't for a specific project I'll clock in this task. Punching-in anywhere clocks in this
Organization task as the default task.

If I want to change the default clocking task I just visit the new task in any org buffer and clock
it in with C-c C-x C-i. Now this new task that collects miscellaneous clock minutes when the clock
would normally stop.

You can quickly clock in the default clocking task with C-u C-c C-x C-i d. Another option is to
repeatedly clock out so the clock moves up the project tree until you clock out the top-level task
and the clock moves to the default task.

Using the clock history to clock in old tasks

You can use the clock history to restart clocks on old tasks you've clocked or to jump directly to a
task you have clocked previously. I use this mainly to clock in whatever got interrupted by
something.

Consider the following scenario:

You are working on and clocking Task A (Organization)

You get interrupted and switch to Task B (Document my use of org-mode)

You complete Task B (Document my use of org-mode)

Now you want to go back to Task A (Organization) again to continue

This is easy to deal with.

Clock in Task A, work on it

Go to Task B (or create a new task) and clock it in

When you are finished with Task B hit C-u C-c C-x C-i i

This displays a clock history selection window like the following and selects the interrupted [i]
entry.

Clock Everything - Create New Tasks

In order to clock everything you need a task for everything. That's fine for planned projects but
interruptions inevitably occur and you need some place to record whatever time you spend on that
interruption.

To deal with this we create a new capture task to record the thing we are about to do. The workflow
goes something like this:

You are clocking some task and an interruption occurs

Create a quick capture task journal entry C-c c j

Type the heading

go do that thing (eat lunch, whatever)

file it C-c C-c, this restores the clock back to the previous clocking task

clock something else in or continue with the current clocking task

This means you can ignore the details like where this task really belongs in your org file layout
and just get on with completing the thing. Refiling a bunch of tasks later in a group when it is
convenient to refile the tasks saves time in the long run.

If it's a one-shot uninteresting task (like a coffee break) I create a capture journal entry for it
that goes to the diary.org date tree. If it's a task that actually needs to be tracked and marked
done, and applied to some project then I create a capture task instead which files it in refile.org.

Finding tasks to clock in

To find a task to work on I use one of the following options (generally listed most frequently used
first)

Use the clock history C-c I
Go back to something I was clocking that is not finished

Pick something off today's block agenda
SCHEDULED or DEADLINE items that need to be done soon

Pick something off the NEXT tasks agenda view
Work on some unfinished task to move to completion

Pick something off the other task list

Use an agenda view with filtering to pick something to work on

Punching in on the task you select will restrict the agenda view to that project so you can focus on
just that thing for some period of time.

Editing clock entries

Sometimes it is necessary to edit clock entries so they reflect reality. I find I do this for maybe
2-3 entries in a week.

Occasionally I cannot clock in a task on time because I'm away from my computer. In this case the
previous clocked task is still running and counts time for both tasks which is wrong.

I make a note of the time and then when I get back to my computer I clock in the right task and edit
the start and end times to correct the clock history.

To visit the clock line for an entry quickly use the agenda log mode. F12 a l shows all clock
lines for today. I use this to navigate to the appropriate clock lines quickly. F11 goes to the
current clocked task but the agenda log mode is better for finding and visiting older clock entries.

Use F12 a l to open the agenda in log mode and show only logged clock times. Move the cursor down
to the clock line you need to edit and hit TAB and you're there.

To edit a clock entry just put the cursor on the part of the date you want to edit (use the keyboard
not the mouse - since the clicking on the timestamp with the mouse goes back to the agenda for that
day) and hit the S-<up arrow> or S-<down arrow> keys to change the time.

The following setting makes time editing use discrete 5-minute intervals (no rounding) increments:

(setq org-time-stamp-rounding-minutes (quote(05)))

Editing the time with the shift arrow combination also updates the total for the clock line which is
a nice convenience.

I always check that I haven't created task overlaps when fixing time clock entries by viewing them
with log mode on in the agenda. There is a new view in the agenda for this – just hit v c in the
daily agenda and clock gaps and overlaps are identified.

This setting just keeps my clocked log entries clean - only keeping clock entries that contribute to
the clock report.

To check for unclosed clock times I use the agenda-view clock check (v c in the agenda). This view
shows clocking gaps and overlaps in the agenda.

To check the last month's clock data I use F12 a v m b v c which shows a full month in the agenda,
moves to the previous month, and shows the clocked times only. It's important to remove any agenda
restriction locks and filters when checking the logs for gaps and overlaps.

The clocked-time only display in the agenda makes it easy to quickly scan down the list to see if an
entry is missing an end time. If an entry is not closed you can manually fix the clock entry based
on other clock info around that time.

Using clock reports to summarize time spent

To get a report of time spent on tasks for XYZ.org you simply visit the XYZ.org file and run an
agenda clock report for the last month with F12 < a v m b R. This limits the agenda to this one
file, shows the agenda for a full month, moves to last month, and generates a clock report.

My agenda org clock report settings show 6 levels of detail with links
to the tasks. I like wider reports than the default compact setting
so I override the :narrow value.

I have since moved to using agenda clock reports shortly after that feature was added. I find this
much more convenient. The data isn't normally for consumption by anyone else so the format of the
agenda clock report format is great for my use-case.

Task Estimates and column view

Estimating how long tasks take to complete is a difficult skill to master. Org-mode makes it easy to
practice creating estimates for tasks and then clock the actual time it takes to complete.

By repeatedly estimating tasks and reviewing how your estimate relates to the actual time clocked
you can tune your estimating skills.

To create an estimate for a task or subtree start column mode with C-c C-x C-c and collapse the
tree with c. This shows a table overlayed on top of the headlines with the task name, effort
estimate, and clocked time in columns.

With the cursor in the Effort column for a task you can easily set the estimated effort value with
the quick keys 1 through 9.

After setting the effort values exit column mode with q.

Reviewing your estimate

Column view is great for reviewing your estimate. This shows your estimated time value and the
total clock time for the project side-by-side.

Creating a dynamic clock table with C-c C-x i RET is a great way to save this project review if
you need to make it available to other applications.

C-c C-x C-d also provides a quick summary of clocked time for the current org file.

Providing progress reports to others

When someone wants details of what I've done recently I simple generate a log report in the agenda
with tasks I've completed and state changes combined with a clock report for the appropriate time
period.

The following setting shows closed tasks and state changes in the agenda. Combined with the agenda
clock report ('R') I can quickly generate all of the details required.

To generate the report I pull up the agenda for the appropriate time frame (today, yesterday, this
week, or last week) and hit the key sequence l R to add the log report (without clocking data
lines) and the agenda clock report at the end.

Then it's simply a matter of exporting the resulting agenda in some useful format to provide to
other people. C-x C-w /tmp/agenda.html RET exports to HTML and C-x C-w /tmp/agenda.txt RET
exports to plain text. Other formats are available but I use these two the most.

Combining this export with tag filters and C-u R can limit the report to exactly the tags that
people are interested in.

Tags

Tasks can have any number of arbitrary tags. Tags are used for:

filtering todo lists and agenda views

providing context for tasks

tagging notes

tagging meetings

tagging tasks to be refiled

tagging tasks in a WAITING state because a parent task is WAITING

tagging cancelled tasks because a parent task is CANCELLED

preventing export of some subtrees when publishing

I use tags mostly for filtering in the agenda. This means you can find tasks with a specific tag
easily across your large number of org-mode files.

Some tags are mutually exclusive. These are defined in a group so that only one of the tags can be
applied to a task at a time (disregarding tag inheritance). I use these types for tags for applying
context to a task.

Tasks are grouped together in org-files and a #+FILETAGS: entry applies a tag to all tasks in the
file. I use this to apply a tag to all tasks in the file. My refile.org file creates a REFILE file
tag so I can filter tasks in the agenda in the refile.org file easily.

Tags

Here are my tag definitions with associated keys for filtering in the agenda views.

The startgroup - endgroup (@XXX) tags are mutually exclusive - selecting one removes a similar tag
already on the task. These are the context tags - you can't be in two places at once so if a task is
marked with @work and you add @home then the @work tag is removed automagically.

The other tags WAITING .. FLAGGED are not mutually exclusive and
multiple tags can appear on a single task. Some of those tags are
created by todo state change triggers. The shortcut key is used to
add or remove the tag using C-c C-q or to apply the task for
filtering on the agenda.

Filetags

Filetags are a convenient way to apply one or more tags to all of the headings in a file.

Filetags look like this:

#+FILETAGS: REFILE work

State Trigger Tags

The following tags are automatically added or removed by todo state triggers described previously in
Todo state triggers

REVIEW

WAITING

HOLD

CANCELLED

Handling Notes

Notes are little gems of knowledge that you come across during your day. They are just like tasks
except there is nothing to do (except learn and memorize the gem of knowledge). Unfortunately
there are way too many gems to remember and my head explodes just thinking about it.

org-mode to the rescue!

Often I'll find some cool feature or thing I want to remember while reading the org-mode and git
mailing lists in Gnus. To create a note I use my note capture template C-c c n, type a heading
for the note and C-c C-c to save it. The only other thing to do is to refile it (later) to the
appropriate project file.

I have an agenda view just to find notes. Notes are refiled to an appropriate project file and
task. If there is no specific task it belongs to it goes to the catchall * Notes task. I
generally have a catchall notes task in every project file. Notes are created with a NOTE tag
already applied by the capture template so I'm free to refile the note anywhere. As long as the
note is in a project file that contributes to my agenda (ie. in org-agenda-files) then I can find
the note back easily with my notes agenda view by hitting the key combination F12 N. I'm free to
limit the agenda view of notes using standard agenda tag filtering.

Short notes with a meaningful headline are a great way to remember technical details without the
need to actually remember anything - other than how to find them back when you need them using
F12 N.

Notes that are project related and not generally useful can be archived with the project and
removed from the agenda when the project is removed.

GTD Stuff

Project definition and finding stuck projects

I'm using a new lazy project definition to mark tasks as projects. This requires zero effort from
me. Any task with a subtask using a todo keyword is a project. Period.

Projects are 'stuck' if they have no subtask with a NEXT todo keyword task defined.

The org-mode stuck projects agenda view lists projects that have no NEXT task defined. Stuck
projects show up on my block agenda and I tend to assign a NEXT task so the list remains empty.
This helps to keep projects moving forward.

I disable the default org-mode stuck projects agenda view with the following setting.

(setq org-stuck-projects (quote("" nil nil "")))

This prevents org-mode from trying to show incorrect data if I select the default stuck project view
with F12 # from the agenda menu. My customized stuck projects view is part of my block agenda
displayed with F12 SPC.

Projects can have subprojects - and these subprojects can also be stuck. Any project that is stuck
shows up on the stuck projects list so I can indicate or create a NEXT task to move that project
forward.

In the following example Stuck Project A is stuck because it has no subtask which is NEXT.
Project C is not stuck because it has NEXT tasks SubTask G and Task I. Stuck Sub Project D
is stuck because SubTask E is not NEXT and there are no other tasks available in this project.

All of the stuck projects and subprojects show up in the stuck projects list and that is my
indication to assign or create NEXT tasks until the stuck projects list is empty. Occasionally
some subtask is WAITING for something and the project is stuck until that condition is satisfied.
In this case I leave it on the stuck project list and just work on something else. This stuck
project 'bugs' me regularly when I see it on the block agenda and this prompts me to follow up on
the thing that I'm waiting for.

I have the following helper functions defined for projects which are used by agenda views.

Archiving

Archiving Subtrees

My archiving procedure has changed. I used to move entire subtrees to a separate archive file for
the project. Task subtrees in FILE.org get archived to FILE.org_archive using the a y command
in the agenda.

I still archive to the same archive file as before but now I archive any done state todo task that
is old enough to archive. Tasks to archive are listed automatically at the end of my block agenda
and these are guaranteed to be old enough that I've already billed any time associated with these
tasks. This cleans up my project trees and removes the old tasks that are no longer interesting. The
archived tasks get extra property data created during the archive procedure so that it is possible
to reconstruct exactly where the archived entry came from in the rare case where you want to
unarchive something.

My archive files are huge but so far I haven't found a need to split them by year (or decade) :)

Archivable tasks show up in the last section of my block agenda when a new month starts. Any tasks
that are done but have no timestamps this month or last month (ie. they are over 30 days old) are
available to archive. Timestamps include closed dates, notes, clock data, etc - any active or
inactive timestamp in the task.

Archiving is trivial. Just mark all of the entries in the block agenda using the m key and then
archive them all to the appropriate place with B $. This normally takes less than 5 minutes once a
month.

Archive Setup

I no longer use an ARCHIVE property in my subtrees. Tasks can just archive normally to the
Archived Tasks heading in the archive file.

The following setting ensures that task states are untouched when they are archived. This makes it
possible to archive tasks that are not marked DONE. By default tasks are archived under the
heading * Archived Tasks in the archive file.

This archiving function does not keep your project trees intact. It archives done state tasks after
they are old enough to they are removed from the main org file. It should be possible to reconstruct
the original tree from the archive detail properties but I've never needed to do this yet. The
archived detail is very useful the few times a year I actually need to look for some archived data
but most of the time I just move it out of the way and keep it for historical purposes.

Archive Tag - Hiding Information

The only time I set the ARCHIVE tag on a task is to prevent it from opening by default because it
has tons of information I don't really need to look at on a regular basis. I can open the task with
C-TAB if I need to see the gory details (like a huge table of data related to the task) but normally
I don't need that information displayed.

When to Archive

Archiving monthly works well for me. I keep completed tasks around for at least 30 days before
archiving them. This keeps current clocking information for the last 30 days out of the archives.
This keeps my files that contribute to the agenda fairly current (this month, and last month, and
anything that is unfinished). I only rarely visit tasks in the archive when I need to pull up
ancient history for something.

Archiving keeps my main working files clutter-free. If I ever need the detail for the archived tasks
they are available in the appropriate archive file.

Publishing and Exporting

I don't do a lot of publishing for other people but I do keep a set of private client system
documentation online. Most of this documentation is a collection of notes exported to HTML.

Everything at https://writequit.org is generated by publishing org-files. This includes the index
pages on this site.

Org-mode can export to a variety of publishing formats including (but not limited to)

ASCII
(plain text - but not the original org-mode file)

HTML

LaTeX

Docbook
which enables getting to lots of other formats like ODF, XML, etc

PDF via LaTeX or Docbook

I use org-publishing combined with TRAMP to publish org-mode files to https://writequit.org so
others can see them, there's a nice built in way of doing it, so I don't even have to change
anything!

Then, when I'm editing ~/org/es/feature-foo.org, I can hit C-c C-e P f and export the file to show
up in http://p.writequit.org/org

exporting to Github-flavored markdown

By and large, 90% of the exports I do are to Github's markdown. Usually to share for an issue. So
there's a nice exporter that does this for me: ox-gfm. While Github does support org-mode as a
file format (or in gists), it doesn't support org syntax in the body of issues or PR comments, so I
need a way to generate that syntax.

Now you just create a begin-src block for the appropriate tool, edit the text, and build the
pictures with C-c C-c. After evaluating the block results are displayed. You can toggle display of
inline images with C-c C-x C-v

I disable startup with inline images because when I access my org-files from an SSH session without
X this breaks (say from my Android phone) it fails when trying to display the images on a non-X
session. It's much more important for me to be able to access my org files from my Android phone
remotely than it is to see images on startup.

;; Don't enable this because it breaks access to emacs from my Android phone(setq org-startup-with-inline-images nil)

Allow asynchronously executing org-babel blocks. Sometimes I run long-running babel executions, and
this allows Emacs not to hang while executing them.

Reminders

I use appt for reminders. It's simple and unobtrusive – putting
pending appointments in the status bar and beeping as 12, 9, 6, 3,
and 0 minutes before the appointment is due.

Everytime the agenda is displayed (and that's lots for me) the
appointment list is erased and rebuilt from the current agenda
details for today. This means everytime I reschedule something, add
or remove tasks that are time related the appointment list is
automatically updated the next time I look at the agenda.

Reminder Setup

(setq appt-message-warning-time 15
appt-display-interval 5);; Erase all reminders and rebuilt reminders for today from the agenda(defunbh/org-agenda-to-appt()(interactive)(setq appt-time-msg-list nil)(org-agenda-to-appt));; Rebuild the reminders everytime the agenda is displayed(add-hook 'org-finalize-agenda-hook'bh/org-agenda-to-appt'append);; This is at the end of my .emacs - so appointments are set up when Emacs starts(bh/org-agenda-to-appt);; Activate appointments so we get notifications(appt-activate t);; If we leave Emacs running overnight - reset the appointments one minute after midnight(run-at-time "24:01" nil 'bh/org-agenda-to-appt)

This makes the bullets into fancy Unicode bullets, rather than ASCII '*' values. Depending on the
theme, it may look better or worse. I also customize the list of bullets because the defaults are a
little wonky looking.

Automatically adding CUSTOM_ID to headlines in a file

(use-packageorg-id:init(setq org-id-link-to-org-use-id 'create-if-interactive-and-no-custom-id)(defuneos/org-custom-id-get(&optional pom create prefix)"Get the CUSTOM_ID property of the entry at point-or-marker POM. If POM is nil, refer to the entry at point. If the entry does not have an CUSTOM_ID, the function returns nil. However, when CREATE is non nil, create a CUSTOM_ID if none is present already. PREFIX will be passed through to `org-id-new'. In any case, the CUSTOM_ID of the entry is returned."(interactive)(org-with-point-at pom
(let((id (org-entry-get nil "CUSTOM_ID")))(cond((and id (stringp id)(string-match "\\S-" id))
id)(create
(setq id (org-id-new (concat prefix "h")))(org-entry-put pom "CUSTOM_ID" id)(org-id-add-location id (buffer-file-name (buffer-base-buffer)))
id)))))(defuneos/org-add-ids-to-headlines-in-file()"Add CUSTOM_ID properties to all headlines in the current file which do not already have one. Only adds ids if the `auto-id' option is set to `t' in the file somewhere. ie, #+OPTIONS: auto-id:t"(interactive)(save-excursion(widen)(goto-char (point-min))(when(re-search-forward "^#\\+OPTIONS:.*auto-id:t"(point-max) t)(org-map-entries (lambda()(eos/org-custom-id-get (point)'create))))));; automatically add ids to saved org-mode headlines(add-hook 'org-mode-hook(lambda()(add-hook 'before-save-hook(lambda()(when(and(eq major-mode 'org-mode)(eq buffer-read-only nil))(eos/org-add-ids-to-headlines-in-file)))))))

Tuning the way Agenda looks

Keep tasks with timestamps visible on the global todo lists

Tasks with dates (SCHEDULED:, DEADLINE:, or active dates) show up in the agenda when
appropriate. The block agenda view (F12 a) tries to keep tasks showing up only in one location
(either in the calendar or other todo lists in later sections of the block agenda.) I now rarely use
the global todo list search in org-mode (F12 t, F12 m) and when I do I'm trying to find a
specific task quickly. These lists now include everything so I can just search for the item I want
and move on.

The block agenda prevents display of tasks with deadlines or scheduled dates in the future so you
can safely ignore these until the appropriate time.

The diary file keeps date-tree entries created by the capture mode 'appointment' template. I use
this also for miscellaneous tasks I want to clock during interruptions.

I don't use a ~/diary file anymore. That is just there as a zero-length file to keep Emacs happy.
I use org-mode's diary functions instead. Inserting entries with i in the emacs agenda creates
date entries in the ~/git/org/diary.org file.