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@438: You will have to enter a project "key" and a project "description". 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@438: Tree mode bernhard@438: --------- bernhard@438: Getan supports a hierarchy of projects. A top level project key bernhard@438: has only one character, once you starting using a second character bernhard@438: as project key, it will be the next level down in the hierarchy. bernhard@438: Example:: bernhard@438: bernhard@438: a Top level project bernhard@438: aa 1st second level project bernhard@438: ab 2nd second level project bernhard@438: aba Third level Project bernhard@438: bernhard@438: Use the switch_project_order key which is ``f2`` by default bernhard@438: to cycle to the hierarchical view. bernhard@438: bernhard@438: 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 `_ 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 _`. bjoern@261: bjoern@288: Install urwid bjoern@288: ------------- ingo_weinzierl@23: bjoern@288: On Debian GNU/Linux >= Wheezy just run as root::: bjoern@288: thomas@507: $ apt-get install python3-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: `_. bjoern@288: bernhard@337: For urwid 1.1.2 the direct download link from pypi is bjoern@340: ``_ 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: thomas@507: $ apt-get install python3-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: thomas@507: $ python3 setup.py install bjoern@288: thomas@508: You may need to install setuptools first, on Debian GNU/Linux just run as root::: thomas@508: thomas@508: $ apt-get install python3-setuptools thomas@508: thomas@508: 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: 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: bernhard@424: mschieder@526: Writing Templates mschieder@526: ================= mschieder@526: mschieder@527: External templates must be stored in ~/.getan/templates/ to be able to call mschieder@527: them. mschieder@527: mschieder@526: Getan uses the Jinja2 templating language. You can find more information mschieder@526: at `Jinja2 `_. mschieder@526: mschieder@526: If a year or a week is specified, only the entries in this period will be mschieder@526: loaded. mschieder@526: mschieder@526: Variables mschieder@526: --------- mschieder@526: mschieder@526: current_week: The current week. mschieder@526: current_year: The current year. mschieder@526: mschieder@526: user: What You indicated with -u. mschieder@526: week: What You indicated with -w. mschieder@526: unix_week: What You indicated with -w, in unix notation. mschieder@526: year: What you indicated with -y. mschieder@526: mschieder@526: get_total_duration(): Total duration of all entries. mschieder@526: mschieder@526: database: Path of the database. mschieder@526: mschieder@526: entries: List of all entries. mschieder@526: get_comment(): Description of the entry. mschieder@526: get_workpackage(): Work package of the entry. mschieder@526: desc: Work package and Description of the entry. mschieder@526: mschieder@526: startisoday: Year, month and day in ISO format. mschieder@526: start: Start time as datetime. mschieder@526: end: End time as datetime. mschieder@526: get_duration(): Duration of the entry. mschieder@526: mschieder@526: projects: List of all projects. mschieder@526: get_total_duration(): Total duration of all mschieder@526: entries in the project. mschieder@526: desc: Description of the project. mschieder@526: key: Key of the project. mschieder@526: mschieder@526: entries: All entries in this project (See entries). mschieder@526: mschieder@526: mschieder@526: If -w is specified, only this week will be loaded from the database. mschieder@526: mschieder@526: year(): All entries in this year. mschieder@526: month(): All entries in this month. mschieder@526: week(): All entries in this week. mschieder@526: day(): All entries in this day. mschieder@526: mschieder@526: Example mschieder@526: ------- mschieder@526: mschieder@526: {{ user }}, (KW {{ week }}, {{ year }}) mschieder@526: {% for i in user -%} mschieder@526: = mschieder@526: {%- endfor -%} mschieder@526: ============== mschieder@526: {% for proj in projects %} mschieder@526: # {{ proj.desc }} mschieder@526: {% for entry in proj.entries|sort(attribute='start') -%} mschieder@526: {{ entry.get_comment() }} mschieder@526: {% endfor -%} mschieder@526: # total time: {{ proj.get_total_duration()|human_time }}h mschieder@526: {% endfor %} mschieder@526: # total: {{ total_time|human_time }}h mschieder@526: mschieder@526: bernhard@424: CREDITS bernhard@424: ======= bernhard@439: Getan is Free Software licensed under the terms of GNU GPL v>=3. bernhard@424: For details see LICENSE coming with the source of 'getan'. bernhard@424: bernhard@424: bernhard@523: Main development bernhard@523: ---------------- bernhard@524: 2018- Magnus Schieder bernhard@524: 2014- Bernhard E. Reiter (current maintainer) bernhard@523: 2011-2014 Björn Ricks bernhard@524: 2010 Ingo Weinzierl bernhard@523: 2009-2014 Thomas Arendsen Hein bernhard@523: 2008-2010 Sascha L. Teichmann bernhard@424: bernhard@424: Contributions bernhard@424: ------------- bernhard@439: Frank Koormann bernhard@424: Stephan Holl bernhard@424: Tom Gottfried bernhard@424: bernhard@424: Thanks bernhard@424: ------ bernhard@424: To all users that gave feedback, especially at Intevation. bernhard@424: bernhard@424: bernhard@417: .. vim: set ts=4 sw=4 tw=80 filetype=rst :