source: stamper/docs/using.rst

0.1
Last change on this file was 48:e1a22d078bbb, checked in by Borja Lopez <borja@…>, 10 years ago

Do not use argparse sphinx integration in the docs.
File size: 5.1 KB

How to use it

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:

stamps -h

or:

stamps --help

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.

[1]http://repos.betabug.ch/stamp
Note: See TracBrowser for help on using the repository browser.