This page will explain how to track your billable hours with Org-mode. It also teaches you how to build a report and create an invoice for a billing cycle. You can do this seamlessly during normal Cyborganize use.
You can do a great deal more with time tracking in Org-mode than this page covers. I’ve provided links for further reading.
Clocking time as you work
Tracking your billable hours in Org-mode is simple, easy and powerful.
Org-mode organizes everything by headlines. Headlines are created with asterisks. * is level one. ** is level two. And so on.
When you start working on a new thing, create a new scratch file and add a level one headline describing the task.
Then use C-q to tag it with the client’s name.
Then clock in to begin timing your work with C-x C-i. You can clock out with C-x o when you stop. Org-mode will display the currently clocked task above the command line at the bottom.
You can jump to the currently clocked in task with C-x C-j
For a list of time clocking commands, see here: http://orgmode.org/manual/Clocking-commands.html
You can see the currently worked time for the task tree with C-c C-x C-d
For subtasks that aren’t billable, you should tag them with “nobill” so that time won’t be added to your total.
When you are done with the scratch file, process it as normal. It will end up fully copied into your notes.org file.
Compiling billable hours for invoices
When you are ready to send an invoice, you need to collect your billable hours data.
First process all your scratch files to ensure that everything will be in notes.org.
Then you will create a clock table, which is an inline report on time worked.
You can learn more about clock tables here: http://orgmode.org/manual/The-clock-table.html#The-clock-table
You can invoke a clock table by creating the following text, and then hitting C-c C-c on the first line:
#+BEGIN: clocktable :maxlevel 4 :scope file :tags “+companyname-nobill-billed”
#+END:
After you hit C-c C-c, your time worked data will appear between the two lines.
There are several parameters after “clocktable” on the first line. I will explain what they do.
:maxlevel controls the level of detail
The :maxlevel parameter controls how much detail is displayed in your clock table.
The number after :maxlevel determines how many outline levels deep of headings will be displayed.
Working hours of lower levels are automatically summed to be included in higher levels. So if you only want to view higher levels, that’s fine.
If some of the lower outline levels are tagged “nobill”, those sums will not be added into the total.
:scope controls area of search
The :scope parameter determines where Org-mode looks for clocked work time.
We will use the “file” scope and execute the clock table in notes.org.
:tags controls which headlines are selected by tag
You can use boolean search logic to select only headlines with the tag combinations you want.
I suggest you use the logic I’ve already provided in the example above.
You must enclose the entire search phrase in quotation marks.
+ means include the following word. – means exclude the following word.
So “+companyname-nobill-billed” means include all headlines with tag “companyname” that don’t have the tags “nobill” or “billed”.
Verify and categorize your data
Go through the data and make sure stuff makes sense. You may have made clocking errors. If so, you can find the offending entry by searching backwards for the headline title, and fix it. Then you can hit C-c C-c on the first line of code for the clocking table to update it.
When you are ready, copy the data table and paste it into Excel. Use paste-special and set the row delimiter as “|” so that it pastes correctly.
You now have your data in Excel. In a typical invoice, you will not provide the level of detail that Org-mode offers. So you need to simplify.
Go through the list of headlines and give each line of work a category name that will make sense to your employer.
You will be able to easily see the auto-summation of totals from lower headlines to higher ones because the indenting will be clearly visible in the spreadsheet. Adjust as needed based on the new categorization.
It will be easier if you mostly stick with the top level headlines you initially created, and don’t try to finesse placing sub-headings into different categories than their top heading. You may have worked on several different things within one scratch session, all under the same main headline. Fudge a bit to save yourself from redoing the math.
It will be much easier to see clocking errors in the spreadsheet. Double check that everything still makes sense. If some task is improperly clocked (typically because you left a clock on all night accidentally) go back to the task’s log book to see what happened. If it’s fixable, fix it. Otherwise just delete that time block from your spreadsheet.
When you’re done categorizing, copy over your data into a new sheet of the spreadsheet. Consolidate times for tasks with identical categories. If necessary, refine the categories further.
You now have a list of tasks and time worked that’s fit to be sent to your client.
Create your billing invoice
I use the “Small Business Invoice Template” from the LibreOffice site. You can download it here: http://templates.services.openoffice.org/en/node/5819
Paste your data into the provided box and customize your personal info. Save the file in Excel format, and including the billing date in the file name. Then hit send.
Save the invoice in a folder with your client info so you can refer back to it later.
Tag billed tasks so you don’t double bill next time
This last step is very important. It will save you headaches when you calculate your work totals for the next billing cycle.
For the last step, we tag all entries with the “companyname” tag as “billed”.
To do this, we use a simple search-replace function within Emacs.
Go to the top of your notes.org file. Execute M-x replace-string. Type the :companyname: tag and hit enter. Then type :companyname:billed: and hit enter again.
The command will execute, replacing all instances of the tag.
If you have done more than one billing cycle with this company, there is one last cleanup step. You want to eliminate instances of double :billed: tags, like this: :companyname:billed:billed:
Go to the top of your notes.org file. Execute M-x replace-string. Type the :billed:billed: and hit enter. Then type :billed: and hit enter again. And you’re done.