1. Trevor Caira
  2. timebook


Trevor Caira  committed 316658b

Added install and readme documentation.

  • Participants
  • Parent commits cc16b53
  • Branches default
  • Tags 1.0

Comments (0)

Files changed (3)


View file
  • Ignore whitespace
+To install timebook, run the following command from the mercurial
+    python setup.py install
+This will install timebook to the default location on your system. To
+install to a different directory, supply setup.py with the ``--prefix``
+option. For details, refer to ``python setup.py install --help`` and the
+python setuptools documentation.
+Alternatively, you can copy or symlink the ``timebook`` subdirectory to
+a directory on your python path, and copy or symlink the ``t``
+executable to a directory on your ``PATH``. This facilitates updating
+through mercurial.


View file
  • Ignore whitespace
+Timebook is a small utility which aims to be a low-overhead way of
+tracking what you spend time on. It can be used to prepare annotated
+time logs of work for presentation to a client, or simply track how you
+spend your free time. Timebook is implemented as a python script which
+maintains its state in a sqlite3 database.
+Timebook maintains a list of *timesheets* -- distinct lists timed
+*periods*. Each period has a start and end time, with the exception of the
+most recent period, which may have no end time set. This indicates that
+this period is still running. Timesheets containing such periods are
+considered *active*. It is possible to have multiple timesheets active
+simultaneously, though a single time sheet may only have one period
+running at once.
+Interactions with timebook are performed through the ``t`` command on
+the command line. ``t`` is followed by one of timebook's subcommands.
+Often used subcommands include ``start``, ``stop``, ``switch``,
+``info``, ``list`` and ``show``. Commands may be abbreviated as long as
+they are unambiguous: thus ``t switch foo`` and ``t sw foo`` are
+identical. Likewise, commands which display timesheets accept
+abbreviated timesheet names. ``t show f`` is thus equivalent to ``t show
+foo`` if ``foo`` is the only timesheet which begins with "f". Note that
+this does not apply to ``t switch``, since this command also creates
+timesheets. (Using the earlier example, if ``t switch f`` is entered, it
+would thus be ambiguous whether a new timesheet ``f`` or switching to
+the existing timesheet ``foo`` was desired).
+The basic usage is as follows::
+  $ t switch writing
+  $ t start document timebook
+  $ t stop
+The first command, ``t switch writing``, switches to the timesheet
+"writing" (or creates it if it does not exist). ``t start document
+timebook`` creates a new period in the current timesheet, and annotates
+it with the description "document timebook". Note that this command
+would be in error if the ``writing`` timesheet was already active.
+Finally, ``t stop`` records the current time as the end time for the
+most recent period in the ``writing`` timesheet.
+To display the current timesheet, invoke the ``t show`` command::
+  $ t show
+  Timesheet writing:
+  Day            Start      End        Duration   Notes
+  Mar 14, 2009   19:53:30 - 20:06:15   0:12:45    document timebook
+                 20:07:02 -            0:00:01    write home about timebook
+                                       0:12:46
+  Total                                0:12:46
+Each period in the timesheet is listed on a row. If the timesheet is
+active, the final period in the timesheet will have no end time. After
+each day, the total time tracked in the timesheet for that day is
+listed. Note that this is computed by summing the durations of the
+periods beginning in the day. In the last row, the total time tracked in
+the timesheet is shown.
+To get a complete listing of commands, see the output of ``t --help``.

File setup.py

View file
  • Ignore whitespace
     version='.'.join(str(bit) for bit in __version__),
-    description='Simple time tracking utility',
+    description='track what you spend time on',
     author='Trevor Caira',