# GNOME Time Tracker Manual

1997-2000
Eckehard Berns
2000
Ximian, Inc.
2001
Linas Vepstas <linas@linas.org>
2007
Goedson Paixão <goedson@debian.org>

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found here.

Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps.

This is version 2.2.3 of the GNOME Time Tracker manual.

## Introduction

### What is GNOME Time Tracker?

GNOME Time Tracker is a combination stop-watch, diary, to-do list tracker and consultant billing system. You can measure the amount of time you spend on a task, associate a memo with it, set a billing rate, print an invoice, as well as track the status of other projects.

You do not need to learn or use every feature in GNOME Time Tracker to be productive: it is meant to be quite usable without requiring a deep study of the documentation. But once you have learned to use GNOME Time Tracker effectively, it can be as effective as any desktop organizer.

Features include:

- Basic Stop-Watch Support At its core, GTT is a fancy stop-watch: you can click on an icon to start and stop one of any number of timers. It is the times measured by these clocks that make up the core data that GTT works with.

- Project Planning Support Well, OK, "project planning" may be an overstatement. But GTT does provide basic to-do list support, including the ability to rank by importance and urgency, specify expected start/stop times, state the project status, and estimate the amount of time needed to complete the project.

- Basic Billing/Invoicing Support GTT has the infrastructure necessary for storing price and billing information. This allows billing invoices to be generated. Tasks can be marked as billable, non-billable, on-hold, or free-of-charge. Billing rates for regular, overtime, double-overtime or flat-fee can be set per task. (Fancier-looking invoices still needed).

- Sub-Project Support New projects can be listed as sub-projects of other projects. The time totals will show the total including sub-projects. The Hierarchical tree can be expanded / collapsed to simplify viewing. The tree can be re-arranged by dragging-n-dropping projects.

- Simple Navigation

  Up/down keys can be used to move up & down on the project list. The left/right arrow keys expand/collapse a sub-project list. Hitting return starts/stops the timer for the selected project.

- Log Journal A journal showing explicit start and stop times is maintained. Blocks of time can be annotated with memos. The journal can be exported as an html page.

- Auto-merge/cleanup of Short Intervals Support Extremely short intervals (the length is configurable) are automatically removed from the logs. Slightly longer but still short intervals are auto-merged into nearby neighbors. Short gaps between intervals are coalesced as well. You can specify a time period of 0 seconds to turn these features off.

- HTML-based GUI The journal GUI is based on extended html pages. If you know HTML, then you can create customized report pages. Particularly handy for slapping the company logo and mailing address on the top of the page, and generating a unique, custom look. User-defined reports (contained in ghtml files) can be added to the menus by typing in the filename into the 'new report' GUI dialog. Typically, a 'user-defined report' is one with customized layout, maybe a logo added, all-spiffed up & such.

- Inactivity Timeout GTT has an inactivity timeout, that will stop the timer after some period of inactivity on both the mouse and keyboard. This period can be configured (or disabled) and the user can decide what to do with the inactivity period when he/she returns (credit all or part of it to the active project or consider as if the timer was inactive for the whole period).

- Shell Commands A shell command can be executed whenever a project timer is started or stopped.

- Scheme Extension Language Scheme (guile) is used as an extension language, although scheme support is currently limited to report generation.

- XML File Format All project and journal data are stored in an XML file format. This should simplify future interoperability and data access concerns.

- Multi-Language Support The basic GTT menus have been translated to dozens of languages. Translations are still needed for the manual.

- DBus support GTT uses DBus to expose some of its functionality. It is currently possible to start/stop the timer or save/reload the data file by sending DBus messages. A shell script named `gnotime-remote` is provided to ease this remote controlling of GTT. See for details on how to use `gnotime-remote`.

GNOME Time Tracker started as part of the package `gnome-utils`, which is a part of the GNOME desktop environment. Now it's maintained as a separate application and is hosted at GnoTime Sourceforge Project. This document describes version &version; of GNOME Time Tracker.

GNOME Time Tracker can be started by selecting Time Tracking Tool from the Office submenu of the Applications, or by running the command `gnotime` on the command line.

## Using GNOME Time Tracker

### Working with GNOME Time Tracker

GNOME Time Tracker can be used to keep track of the amount of time you spend on different things you do. You do this by defining several projects and then, as you go through the day, telling GNOME Time Tracker which project you're working on. It will tell you how much time you spend on each project each day, the total time spent on each project, and the amount of time logged on all projects each day.

Unfortunately, GNOME Time Tracker isn't particularly smart: it won't turn the timer off for you if you take a break for a quick game of solitaire and it turns into several hours of distraction. The inactivity timer will notice that you are still using the keyboard and mouse; it does not know that it's just solitaire. When you stop work on a project, be sure to turn off the timer by clicking the Timer button or using Stop from the Timer menu. As long as you remember to do this, your work will be recorded effectively. You can, however, alter the times from the Activity Report if they are incorrect. See for more information.

GNOME Time Tracker can inform you about your project times in several ways. For each project, it maintains a timer for the amount of time you have spent on the project today, this week, this month, this year, and how much time you have spent on it total. In addition,GNOME Time Tracker counts how much time you have spent on all projects in the current day. This last figure is the one displayed in the lower left hand corner of the status bar.

When you first start GNOME Time Tracker, you see the Main window, as shown in .

#### GNOME Time Tracker Main Window

GNOME Time Tracker Main Window, with a project selected

The main window consists of five areas. There is a menu bar (see ) and a toolbar (see ) at the top of the window, a status bar (see ) at the bottom of the window, and between the toolbar and the status bar, a scrollable project list (see ) and a resizable notes area (see ). When you start GNOME Time Tracker for the first time, the project list area will show you an empty list.

You can customize the appearance of the main window in the preferences dialog. See for more information about changing the toolbar, project list, and time display.

### Menus

Nearly all menu items in GNOME Time Tracker have a shortcut or accelerator key. Shortcuts appear right after the name of the menu item on the menus.

The menu bar consists of six menus: File, Projects, Settings, Reports, Timer and Help.

File

  This menu contains the following commands:

  Ctrl-E Export Tasks — Saves a file containing information about all the tasks for the currently selected project.

  Ctrl-P Export Projects — Saves a file containing information about all top-level projects.

  Ctrl-Q Quit — Closes GNOME Time Tracker, saving projects data and updating the logfile if a logfile is in use.

Projects

  This menu contains the following commands:

  Ctrl-N New ... — brings up the New Project dialog so you can create a new project.

  Ctrl-D Cut — Removes an item from the project list, saving it in memory if you want to paste it back in somewhere else.

  Ctrl-F Copy — Duplicates a selected project, copying it to memory.

  Ctrl-G Paste — Places the project in memory onto the task list. Projects are inserted before the selected item. If no item is selected, they will appear at the bottom of the list.

  Edit Times — Opens the Activity Report for the currently selected project so that you can edit the time intervals currently saved for it.

  Properties... — This selection opens the Properties dialog for the currently selected project. Here you can view and edit the name, description, planning and billing data for your project. Note that this is the same action as the Props button on the toolbar. See for more information.

Settings

  This menu contains only one command: Preferences, which launches the Preferences Dialog. See for more information.

Timer

  This menu contains the following commands:

  Ctrl-S Start — Starts the timer on the selected project.

  Ctrl-W Stop Timer — Stops the timer.

  Ctrl-T Toggle Timer — This item toggles the timer on or off.

Reports

  This menu contains various predefined reports and may have new items added by the user. See for a list of the predefined reports.

Help

  This menu contains the following commands:

  Manual — Shows this manual.

  About — Displays copyright and author information for GNOME Time Tracker.

### The Toolbar

The toolbar is another way to speed up your most frequently performed operations in GNOME Time Tracker. Each icon in it is a shortcut to one of the menu functions. By default, the buttons are:

- New,which opens the New Projectdialog.

- Props,which opens the Properties dialog.

- Timer, which toggles the timer between on and off.

- Prefs, which opens the Preference dialog.

- Manual, which opens this manual.

- Quit, which quits GNOME Time Tracker.

You can choose which functions appear in the toolbar from the Preferences dialog. See for more information.

### Manipulating projects

Projects are the central concept in working with GNOME Time Tracker. In this section we will learn what we can do with projects in GNOME Time Tracker and how to do it.

#### Creating new projects

You need to have projects to work with GNOME Time Tracker. So, the first thing you need to learn is how to create new projects.

To create a new project, you must invoke the by selecting the New ... item from the Projects menu. Alternatively, you may type Ctrl-N or click on the New button in the toolbar.

##### New Project Dialog

New Project Dialog

In the New Project Dialog, you just inform the Project Title and the Project Description. After clicking the OK button, the new project will be added to the Projects List and you're ready to start working on your new project.

#### Navigating through your projects

The project list is located in the central area of the main window. It shows the list of projects and which project is currently selected. Each line corresponds to one project, and displays various attributes of that project. You may choose which attributes are shown in the project list from the Preferences dialog (see ).

You can select a project by clicking on it with the left mouse button. Note that you can only have one project selected at any given time.

You toggle the timer for a project by double clicking it on the project list. You may, alternatively, select it and click on the Timer button in the toolbar or selecting the Timer Running item from the Timer menu.

To get a popup menu for a project, click the right mouse button on it. If the project wasn't selected, it will now receive the selection, and the Project popup menu will be displayed.

#### Editing Project Properties

You may edit the properties of a project by invoking the Project Properties Dialog through the Properties menu item from the Projects menu. This dialog is formed by four tabs named Project, Rates, Intervals and Planning.

The Project tab, which you see in , is where you edit the basic information about your project, like Project Title, Project Description and Notes.

##### Properties Dialog - Project Tab

Properties dialog - project tab

The Rates tab, which you see in , is where you inform the ammount you will be billing for the project. You may enter rates for Normal hours, Overtime hours, Double Overtime hours and a Flat Rate. Then, you can select for each task you do in the project which of these billing types should be used so that the invoices can be calculated correctly.

##### Properties Dialog - Rates Tab

Properties dialog - rates tab

The Intervals tab, which you see in , is where you set your preferences for interval recording and auto-merging for the project. The options presented in this tab are:

- Minimum Interval — the minimum size of interval that will be recorded. Intervals that last less than this will be discarded.
- Auto-merge Interval — the maximum duration for intervals that should be auto-merged. If the duration of an interval is less than this value, it will be automatically merged to its neighbors.
- Auto-merge Gap — the minimum distance between two neighbor intervals that will keep them apart. If the time difference from the end of one interval and the start of the next interval is less than this value, they will be automatically merged.

##### Properties Dialog - Intervals Tab

Properties dialog - intervals tab

If you want to disable any of these automatic interval cleanups, just set the corresponding value to 0.

The Planning tab, which you see in , is where you may enter data about your planning for the execution of the project. The following information may be set for the project:

- Urgency — how urgent this project is
- Importance — how important this project is
- Planned Start — when we plan to start working on this project
- Planned Finish — when we plan to finish working in this project
- Due Date — when the project must be finish
- Hours to Finish — How many hours of work will be needed to finish this project
- &percnt; Complete — How much of the project has already been done

##### Properties Dialog - Planning Tab

Properties dialog - planning tab

### The Status Bar

The first field of the status bar displays the sum of all projects' daily time. It reflects the total time you have worked on your projects today.

The second field holds the title and description of the currently active project. If no project is active, the display reads: `Timer is not running`.

The far right corner of the status bar holds a small clock if the timer is running. If the timer is off, the space is blank.

## Customization

To change default settings, select the Preferences command in the Settings menu. This launches the Preferences dialog. There are seven tabs of preferences in the window.

### The Fields Preferences Tab

Through this tab, shown in , you can control which information is shown in the project list. The following fields may be enabled or disabled by toggling the buttons present in this tab:

- Project Importance — importance of the project as defined in the
- Project Urgency — urgency of the project as defined in the
- Project Status — status of the project as defined in the
- Total Time — total time worked on the project since its creation
- Time this year — total time worked on the project this year
- Time this month — total time worked on the project this month
- Time this week — total time worked on the project this week
- Time last week — total time worked on the project last week
- Time today — total time worked on the project today
- Time yesterday — total time worked on the project yesterday
- Time for the current diary entry — total time worked on the project for the current diary entry
- Project description — description of the project as defined in the
- Current diary entry — title of the current diary entry
- Planned project start date — start date of the project as defined in the
- Planned project end date — end date of the project as defined in the
- Project due date — due date for the project as defined in the
- Estimated effort — estimated work time for the project as defined in the
- Percent complete — percent of the project already done as defined in the

#### Preferences Dialog - Fields Tab

Preferences dialog - fields tab

### The Display Preferences Tab

This tab, shown in , controls some aspects of the main window display. The following aspects may be controlled through the settings available in this tab:

- Show seconds — display seconds in the various time counters
- Show statusbar — show the statusbar at the bottom of the window
- Show Table Header — display the headers with names of the fields in the Project List
- Show Sub-projects — display the project tree structure through lines linking the projects to its sub-projects

#### Preferences Dialog - Display Tab

Preferences dialog - display tab

### The Shell Preferences Tab

This tab, shown in , allows you to define commands to be executed when starting or stopping the timer for a project. When composing your command line, you may use the following variables:

- `&percnt;t` — The project's title.

- `&percnt;d` — The project's description.

- `&percnt;T` — The total time logged on the project, in the format Hours:Minutes:Seconds.

- `&percnt;h` — The number of hours logged on the project today.

- `&percnt;H` — The number of hours spent on the project today, in two digits.

- `&percnt;m` — The number of minutes spent on the project today.

- `&percnt;M` — The number of minutes spent on the project today (00-59).

- `&percnt;s` — The number of seconds spent on the project today.

- `&percnt;S` — The number of seconds spent on the project today (00-59).

#### Preferences Dialog - Shell Tab

Preferences dialog - shell tab

### The Logfile Preferences Tab

This tab, shown in , contains a Use Logfile Checkbox, which determines whether you use a logfile at all, and the following text entry boxes, governing its behavior:

- Filename Determines the path and name of the log file. This should be the complete path and filename, without variables like $HOME or ~.

- Entry Start This is the string which marks the start of a log entry. It can include the same variables as described in .

- Entry Stop This string marks the end of a log entry. It can include the same variables as described in .

- Min Recorded The minimum size of intervals that should be recorded in the logfile.

#### Preferences Dialog - Logfile Tab

Preferences dialog - logfile tab

Note that a project will not get logged until you either quit GNOME Time Tracker, switch to another project, or deselect that project. Don't be confused when you look at your logfile and your current project still isn't listed, even if it has been running for two hours.

### The Toolbar Preferences Tab

This tab, shown in , contains two sections of buttons: Toolbar and Toolbar Segments

#### Preferences Dialog - Toolbar Tab

Preferences dialog - toolbar tab

- The Toolbar section contains the following checkboxes:

  - Show Toolbar
  - Show Tooltips
  They determine whether the toolbar buttons should be displayed and whether tooltips describing the button should appear when the mouse pointer hovers over a toolbar item. The control of wheter text, icons or both should be shown in the toolbar buttons is done through the global GNOME toolbar settings.

- The Toolbar Segments checkboxes determine which shortcut buttons appear on the toolbar:

  - Show 'New'
  - Show 'Cut', 'Copy', 'Paste'
  - Show 'Journal'
  - Show 'Properties'
  - Show 'Timer'
  - Show 'Preferences'
  - Show 'Help'
  - Show 'Quit'

### The Misc Preferences Tab

This tab, shown in , contains three sections.

#### Preferences Dialog - Misc Tab

Preferences dialog - misc tab

Inactivity Timeout

  The Inactivity timeout defines the number of seconds of inactivity after which GnoTime will stop the timer and alert the user if the timer was running and give her/him the opportunity to tune how much of that time should really be credited to the active project. If you don't want this timeout to be active, set this value to zero or some negative value.

No Project Timeout

  The No Project Timeout defines the number of seconds after which GnoTime will alert the user if there is no active project and offer to start the timer running for some project and credit the elapsed time to it. If you don't want this timeout to be active, set this value to zero or some negative value.

End of Day/Week

  The End of Day/Week section allows the user to define at which time of day GnoTime should start counting as a different day and which day of the week should be considered as the start of a new week.

### The Reports Preferences Tab

This tab, shown in , contains two sections that allow users to choose how some values are formated in reports.

#### Preferences Dialog - Reports Tab

Preferences dialog - reports tab

Time format

  This option allows you to choose how times should be displayed in reports. You may choose among a 12 hours format, 24 hours or the default format based on your current locale settings.

Currency settings

  This option allows you to set a customized currency symbol to be used in reports or choose to use the currency symbol defined by your locale settings.

### OK, Apply and Close

If you are pleased by the changes you have made, click OK to activate the changes and have the dialog go away.

If you want to see what your changes will look like without closing the window, press Apply to activate the values while keeping the dialog open.

If you don't want to activate your changes, press Close. That will close the dialog, but will not save any of the changes you have made. This does not reverse any changes activated by the Apply command. Note that pressing Apply and then Close has the the same effect as pressing OK.

## The timeout dialogs

As we have seen at , GNOME Time Tracker allows you to define two timeouts for conditions in which it will popup a dialog to warn about it and let you take action to correct the situation. In this section, we will learn how these dialogs work.

### The Restart Timer Dialog

When GNOME Time Tracker detects that you have not entered anything into your computer for a period of time (configured under ), it stops the timer and pops up a dialog asking if you want to restart the timer.

#### Restart Timer Dialog

Restart Timer Dialog

If you want the time credited to the project anyway (If you had to make a call related to the project, for instance) GnoTime provides a slider which can be set to the time you want to credit the project with. Pressing Yes credits the project and restarts the timer. Pressing No halts the timer.

### Start Project Dialog

Similarly, when there is no project running, GNOME Timer Tracker pops up a dialog asking if you want to start one.

#### No Project Dialog

Start Project Dialog

It provides a drop-down list of your projects which you can choose to select as well as a place to enter any time you want credited to the timer. If you choose to restart the timer with a project, press the Execute button. Otherwise, press Cancel.

## Reports

GnoTime provides a set of default reports that can be used to take different views to your project data ranging from a detailed listing of the work done with all time interval data recorded to an invoice listing the each task and it's billing status and value. Some of these reports may be used to edit data that you would not be able to do otherwise (You're right, that's a bug in the application and we should fix it in the future but, for now, it's good to know how you can access these data while we don't fix it). Some samples of the default reports can be seen below.

### The Journal Report

The journal report displays a summary of the Diary Entries associated with a project containing its title, date and time of first activity, date and time of last activity, and the notes associated. An example of a Journal Report for a project containing only one Diary Entry can be seen in .

#### Journal Report

Journal Report

By clicking the title of a Diary Entry in the report, you activate the Diary Entry menu, from which you can do various operations like creating a new diary entry, editing the properties of the diary entry, deleting/copying/pasting the diary entry and creating a new time interval for the diary entry.

### The Activity Report

The activity report displays a list of the diary entries for a project detailing the start and stop times for each of the recorded time intervals. An example of an Activity Report can be seen in .

#### Activity Report

Activity Report

Clicking in a time interval's data, you will activate the Time Interval menu which will allow you to edit its data, cut, copy, paste, merge to its neighbors and create new time intervals.

### The Todo Report

The todo report lists all the sub-projects of a given project, displaying its importance, urgency, title, description and status. An example Todo Report is shown in .

#### Todo Report

Todo Report

Clicking the title of a sub-project will take you to the Journal Report for that sub-project.

### The Invoice Report

The Invoice Report displays the list of billable tasks for a project with its respective worked time and value. An example Invoice Report can be seen at .

#### Invoice Report

Invoice Report

### The Daily Report

The Daily Report shows the total time worked each day for a given project with a list of the tasks worked on each day. An example Daily Report can be seen at .

#### Daily Report

Daily Report

### Customizing Reports

We know GnoTime's default set of reports will not satisfy all the reporting needs for everyone. They may be missing some data, or may be showing data you don't want to be shown or may be pretty ugly or simply we may have not envisioned some that particular way you want to display your data.

Fortunately, the available reports are not set in stone. GnoTime's reporting engine is based on HTML files with scheme scripting. So you can edit them at will to change their formating, add or remove data and even create whole new reports and add them to the set of reports available from the Reports menu. If you do create some new report you think could be useful for the community in general, you may post it in our patch tracker and we will consider its inclusion in future releases.

To add a new report to GnoTime, you choose Reports New report, which will invoke the . In this dialog, you must enter the name that should be displayed in the Reports menu for the new report you are creating, a tooltip to be displayed for the menu item and the full path to the file with the code for the new report.

#### New Report Dialog

New Report Dialog

After adding new reports to GnoTime, you may want to organize the menu items in a different way, instead of keeping them in a flat list in the order the were added. To do this, you choose Reports Edit Reports, which will open the . In this dialog, you will be able to reorder the menu items, create sub menus, create keyboard shortcuts for the reports, and change all the properties entered when creating the report.

#### Edit Reports Dialog

Edit Reports Dialog

## Sending commands to GnoTime

GNOME Time Tracker exposes some of its functionality through DBus. To ease the use of the exposed functions, we provide a shell script named gnotime-remote that can be used to send commands to GnoTime. Currently, the following commands are supported:

- `start-timer` — starts the timer for the currently selected project
- `stop-timer` — stops the timer
- `save-file` — saves project data to the data file
- `reload-file` — reloads project data from the data file

## Known bugs and limitations

You may refer to the GnoTime Sourceforge Project Site for a list of known bugs.

## Authors

GNOME Time Tracker was written by Eckehard Berns eb@berns.i-s-o.net and Linas Vepstas linas@linas.org. It is currently maintained by Goedson Paixão goedson@debian.org.

Please submit all comments, suggestions, and bug reports on the GnoTime Sourceforge Project Site; you may want to drop Goedson an email as well.

There is a web page devoted to the latest GTT news at http://gttr.sourceforge.net (mirrored at http://www.linas.org/linux/gtt/gtt.html).

This manual was written by Aaron Weber (aaron@helixcode.com) Eckehard Berns (eb@berns.i-s-o.net) Linas Vepstas (linas@linas.org) and Goedson Paixão (goedson@debian.org) Please send all comments and suggestions regarding the manual to our bug tracker at the SourceForge project page.

## License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You may obtain a copy of the GNU General Public License from the Free Software Foundation by visiting their Web site or by writing to

            Free Software Foundation, Inc.
            51 Franklin Street - Fifth Floor
            Boston, MA 02110-1301
            USA