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