How to use it
=============

.. contents::


Recording time
--------------

To start recording time::

  stamp

To stop recording time::

  stamp ID DESCRIPTION

where:

- **ID** is a string **without spaces** identifying a customer, project,
  group of tasks or any other thing you want to use to group your stamps

- **DESCRIPTION** is a description of what you did

for example::

  stamp stamper writing documentation

or::

  stamp stamper implementing per-month line charts


Recording consecutive stamps
++++++++++++++++++++++++++++

Imagine you start working on a project, you *stamp* your start::

  stamp

and then you finish a given task, so you *stamp* it::

  stamp stamper writing installation instructions

but then, you keep yourself working on the same project, but on some other
task. You don't have to *stamp* the start time again, you simply *stamp* again
when you finish the work on that other task::

  stamp stamper writing usage instructions

.. note::

   This apply also for changing to another project, you don't have to *stamp*
   the start time again, just keep stamping the end times. In such a situation,
   Stamper will take the end time of a recorded stamp as the start time of the
   next one.


Retrieving information from the existing stamps
-----------------------------------------------

Total times
+++++++++++

- Get a list of total times stamped per **ID**::

    stamps

- Get the total times stamped for a given **ID**, for example, **stamper**::

    stamps stamper

- Get the total times stamped for the **ID** **stamper** during the last
  week::

    stamps stamper 1w

  .. seealso::

     *1w* is a date-based filter. You can learn more about those filters
     in the :ref:`date_based_filtering` documentation below.

Per day details
+++++++++++++++

- Get a list of detailed per-day times::

    stamps -v

- Get details for a given **ID**, for example, **stamper**::

    stamps -v stamper

- Get details for a given month, for example, *august 2014*::

    stamps -v 2014-08-01--2014-09-01

  .. seealso::

     *2014-08-01--2014-09-01* is a date-based filter. You can learn more about
     those filters in the :ref:`date_based_filtering` documentation below.

Timeline
++++++++

You can get a *timeline* of all the stamped stamps::

  stamps -t

This *timeline* will show each stamp in a line, in a similar way to what bebu's
stamp [1]_ stores in its text-based file::

  2014-08-12 12:33 start
  2014-08-12 12:51 stamper writing installation instructions
  2014-08-12 13:11 stamper writing usage documentation
  2014-08-13 09:33 start
  2014-08-13 12:12 stamper adding missing tests for the cli tools

You can filter the timeline by **ID**::

  stamps -t stamper

And/or by date::

  stamps -t 2m

  .. seealso::

     *2m* is a date-based filter. You can learn more about those filters
     in the :ref:`date_based_filtering` documentation below.


Charts
++++++

You can generate some nice charts from your stamps. So far only bar charts
showing the total time per day can be generated, but you can filter them by
**ID** and/or date. Some examples:

- Render a chart of all the times already stamped, by **ID**::

    stamps -g

- Render a chart of the stamps for the last 4 days::

    stamps -g 4d

- Render a chart of the stamps for the **ID** *stamper* for the last week::

    stamps -g stamper 1w

.. note::

   The charts will be saved into **~/.workstamps-charts**, in SVG_ format.
   The name of the chart will be generated based on the current date and
   time, and a *symbolic link* called **chart-latest.svg** will be created,
   pointing to the latest chart generated.


stamps - full List of arguments
-------------------------------

You can get the full list of arguments from the command line too::

  stamps -h

or::

  stamps --help

.. argparse::
   :module: stamper.cli
   :func: build_args_parser
   :prog: stamper


.. _date_based_filtering:

Date-based filtering
--------------------

Most of the results returned by the *stamps* tool can be filtered using the
following date-based filters:

- **YYYY-MM-DD**: Limit the results to only those stamps stamped on this date::

    stamps -v 2014-08-13

  ::

    stamps -t stamper 2014-08-13

- **YYYY-MM-DD\***: Limit the results to only those stamps stamped **after this
  date**. For example, this will show per-day details for stamps stamped after
  the first of august, 2014::

    stamps -v 2014-08-01*

- **\*YYYY-MM-DD**: Limit the results to only those stamps stamped **before this
  date**. For example this will show the total time stamped for project stamper
  before the first of january, 2014::

    stamps stamper *2014-01-01

- **YYYY-MM-DD--YYYY-MM-DD**: Limit the results to only those stamps stamped in
  a date **between those dates**. For example, this will show the *timeline* for
  july, 2014::

    stamps -t 2014-07-01--2014-08-01

- **nD|W|M|Y**: Limit the results to only those stamps stamped since n *days*
  (**D**), *weeks* (**W**), *months* (**M**) or *years* (**Y**) ago.
  For example, this will show the details for the last month::

    stamps -v 1m

  .. note::

     It does not matter if you provide *d|w|m|y* or *D|W|M|Y*. The filters are
     handled in a case-insensitive way.


.. _SVG: http://en.wikipedia.org/wiki/Scalable_Vector_Graphics

.. [1] http://repos.betabug.ch/stamp