bernhard@417: Usage
bernhard@417: =====
bernhard@417: 
bernhard@417: Call ``getan`` or ``getan.py`` in a terminal to start
bernhard@417: with an empty list of tasks that you want to track time for.
bernhard@417: 
bernhard@417: Use the Insert-Key to add a new task to track.
bernhard@417: (A *task* is called *project* within getan.)
bernhard@417: 
bernhard@417: Now select one of the projects with the arrow keys from your keyboard
bernhard@417: and press enter to start the clock. See ``INTRODUCTION`` for more keyboard
bernhard@417: commands.
bernhard@417: 
bernhard@418: The time log entries will be saved in an sqlite database,
bernhard@418: by default getan will create ``~/.getan/time.db``.
bernhard@417: The ``scripts/`` will help to generate reports from them.
bernhard@417: 
bernhard@418: Customization
bernhard@418: -------------
bernhard@418: 
bernhard@418: Use ``~/.getan/getanrc`` or the system-wide ``/etc/getanrc``
bernhard@418: to customize keys and colors. See ``getan/config.py`` for
bernhard@418: the recognized options. Example::
bernhard@418: 
bernhard@418:     [keybindings]
bernhard@418:     # changes the insert function to be activated by the `)` key
bernhard@418:     insert: )
bernhard@418: 
bernhard@418:     [theme]
bernhard@418:     header: light green, dark green
bernhard@418:     body: light green, black
bernhard@418: 
bernhard@418: 
bernhard@418: 
bjoern@288: Installation
bjoern@288: ============
teichmann@0: 
bernhard@336: Getan requires `urwid <http://urwid.org/>`_ in a version >= 1.0. Urwid is
bjoern@367: a console user interface library written in Python. For console output e.g.
bjoern@367: zeiterfassung.py Getan also requires `Jinja2 <http://jinja.pocoo.org/>_`.
bjoern@261: 
bjoern@288: Install urwid
bjoern@288: -------------
ingo_weinzierl@23: 
bjoern@288: On Debian GNU/Linux >= Wheezy just run as root:::
bjoern@288: 
bjoern@288:     $ apt-get install python-urwid
bjoern@288: 
bjoern@288: On other systems urwid may be installed via pip or directly put into the sources
bjoern@288: of getan.
bjoern@288: 
bjoern@288: Using pip
bjoern@288: ^^^^^^^^^
bjoern@288: 
bjoern@288: To install urwid via pip run as root::
bjoern@288: 
bjoern@288:     $ pip install urwid
bjoern@288: 
bjoern@288: Or if you prefer using a virtualenv::
bjoern@288: 
bernhard@414:     $ virtualenv getan-env
bjoern@288:     $ source getan-env/bin/activate
bernhard@414:     (getan-env)$ pip install -U pip  # to get the latest pip
bjoern@288:     (getan-env)$ pip install urwid
bjoern@288: 
bjoern@288: Using urwid sources
bjoern@288: ^^^^^^^^^^^^^^^^^^^
bjoern@288: 
bjoern@288: Urwid can be put as source to the getan directory when getan is run directly
bjoern@288: from the sources. Urwid source can be downloaded from `pypi
bernhard@336: <https://pypi.python.org/pypi/urwid/>`_.
bjoern@288: 
bernhard@337: For urwid 1.1.2 the direct download link from pypi is
bjoern@340: `<https://pypi.python.org/packages/source/u/urwid/urwid-1.1.2.tar.gz>`_
bjoern@340: (sha256sum is
bjoern@340: f56568b4f8459b3265c65d9e275ef72df6cb16ad0c291f0feb027cc911ea0f26).::
bjoern@288: 
bjoern@288:     $ cd getan-source
bernhard@337:     $ v=urwid-1.1.2
bernhard@337:     $ curl -O https://pypi.python.org/packages/source/u/urwid/$v.tar.gz
bernhard@337:     $ sha256sum $v.tar.gz
bernhard@337:     $ tar -xzvf $v.tar.gz
bernhard@337:     $ ln -s $v/urwid urwid
bjoern@288: 
bjoern@367: Install Jinja2
bjoern@367: --------------
bjoern@367: 
bjoern@367: On Debian GNU/Linux just run as root:::
bjoern@367: 
bjoern@367:     $ apt-get install python-jinja2
bjoern@367: 
bjoern@367: On other systems jinja2 may be installed via pip or directly put into the
bjoern@367: sources of getan.
bjoern@367: 
bjoern@367: Using pip
bjoern@367: ^^^^^^^^^
bjoern@367: 
bjoern@367: To install jinja2 via pip run as root::
bjoern@367: 
bjoern@367:     $ pip install jinja2
bjoern@367: 
bjoern@367: Or if you prefer using a virtualenv::
bjoern@367: 
bjoern@367:     $ source getan-env/bin/activate
bjoern@367:     (getan-env)$ pip install jinja2
bjoern@367: 
bjoern@288: Install getan
bjoern@288: -------------
bjoern@288: 
bjoern@288: A installation of getan is not required. It can also be run directly from the
bjoern@288: sources. To install getan system wide the following command must be run as root
bjoern@288: user::
bjoern@288: 
bjoern@288:     $ python setup.py install
bjoern@288: 
bjoern@288: Starting getan
bjoern@288: ==============
bjoern@288: 
bjoern@288: Getan can be directly run from sources or after a system wide installation from
bjoern@288: the bin dir (e.g. /usr/bin).
bjoern@288: 
bjoern@288: Running from Sources
bjoern@288: --------------------
bjoern@288: 
bjoern@288: To run getan from the sources run::
teichmann@0: 
ingo_weinzierl@23:     $ ./getan.py
teichmann@0: 
bjoern@288: or::
teichmann@0: 
bjoern@288:     $ ./getan.py /path/to/mytime.db
teichmann@0: 
bjoern@341: to choose a different sqlite3 database then the default time.db
bjoern@288: 
bjoern@288: The classic version of 'getan' which is based on curses can be run with::
bjoern@288: 
ingo_weinzierl@23:     $ classic/getan
ingo_weinzierl@23: 
bjoern@288: or::
ingo_weinzierl@23: 
bjoern@288:     $ classic/getan /path/to/mytime.db
bjoern@288: 
bjoern@288: Running from installation
bjoern@288: -------------------------
bjoern@288: 
bjoern@288: After installing getan it can be run with::
bjoern@288: 
bjoern@288:     $ getan
bjoern@288: 
bjoern@288: or::
bjoern@288: 
bjoern@288:     $ getan /path/to/mytime.db
bjoern@288: 
bjoern@288: The classic version of 'getan' is also available::
bjoern@288: 
bjoern@288:     $ getan-classic
bjoern@288: 
bjoern@288: or::
bjoern@288: 
bjoern@288:     $ getan-classic /path/to/mytime.db
bjoern@342: 
bernhard@417: .. vim: set ts=4 sw=4 tw=80 filetype=rst :