[42] | 1 | How to use it
|
---|
| 2 | =============
|
---|
| 3 |
|
---|
| 4 | .. contents::
|
---|
| 5 |
|
---|
| 6 |
|
---|
| 7 | Recording time
|
---|
| 8 | --------------
|
---|
| 9 |
|
---|
| 10 | To start recording time::
|
---|
| 11 |
|
---|
| 12 | stamp
|
---|
| 13 |
|
---|
| 14 | To stop recording time::
|
---|
| 15 |
|
---|
| 16 | stamp ID DESCRIPTION
|
---|
| 17 |
|
---|
| 18 | where:
|
---|
| 19 |
|
---|
| 20 | - **ID** is a string **without spaces** identifying a customer, project,
|
---|
| 21 | group of tasks or any other thing you want to use to group your stamps
|
---|
| 22 |
|
---|
| 23 | - **DESCRIPTION** is a description of what you did
|
---|
| 24 |
|
---|
| 25 | for example::
|
---|
| 26 |
|
---|
| 27 | stamp stamper writing documentation
|
---|
| 28 |
|
---|
| 29 | or::
|
---|
| 30 |
|
---|
| 31 | stamp stamper implementing per-month line charts
|
---|
| 32 |
|
---|
| 33 |
|
---|
| 34 | Recording consecutive stamps
|
---|
| 35 | ++++++++++++++++++++++++++++
|
---|
| 36 |
|
---|
| 37 | Imagine you start working on a project, you *stamp* your start::
|
---|
| 38 |
|
---|
| 39 | stamp
|
---|
| 40 |
|
---|
| 41 | and then you finish a given task, so you *stamp* it::
|
---|
| 42 |
|
---|
| 43 | stamp stamper writing installation instructions
|
---|
| 44 |
|
---|
| 45 | but then, you keep yourself working on the same project, but on some other
|
---|
| 46 | task. You don't have to *stamp* the start time again, you simply *stamp* again
|
---|
| 47 | when you finish the work on that other task::
|
---|
| 48 |
|
---|
| 49 | stamp stamper writing usage instructions
|
---|
| 50 |
|
---|
| 51 | .. note::
|
---|
| 52 |
|
---|
| 53 | This apply also for changing to another project, you don't have to *stamp*
|
---|
| 54 | the start time again, just keep stamping the end times. In such a situation,
|
---|
| 55 | Stamper will take the end time of a recorded stamp as the start time of the
|
---|
| 56 | next one.
|
---|
| 57 |
|
---|
| 58 |
|
---|
| 59 | Retrieving information from the existing stamps
|
---|
| 60 | -----------------------------------------------
|
---|
| 61 |
|
---|
| 62 | Total times
|
---|
| 63 | +++++++++++
|
---|
| 64 |
|
---|
| 65 | - Get a list of total times stamped per **ID**::
|
---|
| 66 |
|
---|
| 67 | stamps
|
---|
| 68 |
|
---|
| 69 | - Get the total times stamped for a given **ID**, for example, **stamper**::
|
---|
| 70 |
|
---|
| 71 | stamps stamper
|
---|
| 72 |
|
---|
| 73 | - Get the total times stamped for the **ID** **stamper** during the last
|
---|
| 74 | week::
|
---|
| 75 |
|
---|
| 76 | stamps stamper 1w
|
---|
| 77 |
|
---|
| 78 | .. seealso::
|
---|
| 79 |
|
---|
| 80 | *1w* is a date-based filter. You can learn more about those filters
|
---|
| 81 | in the :ref:`date_based_filtering` documentation below.
|
---|
| 82 |
|
---|
| 83 | Per day details
|
---|
| 84 | +++++++++++++++
|
---|
| 85 |
|
---|
| 86 | - Get a list of detailed per-day times::
|
---|
| 87 |
|
---|
| 88 | stamps -v
|
---|
| 89 |
|
---|
| 90 | - Get details for a given **ID**, for example, **stamper**::
|
---|
| 91 |
|
---|
| 92 | stamps -v stamper
|
---|
| 93 |
|
---|
| 94 | - Get details for a given month, for example, *august 2014*::
|
---|
| 95 |
|
---|
| 96 | stamps -v 2014-08-01--2014-09-01
|
---|
| 97 |
|
---|
| 98 | .. seealso::
|
---|
| 99 |
|
---|
| 100 | *2014-08-01--2014-09-01* is a date-based filter. You can learn more about
|
---|
| 101 | those filters in the :ref:`date_based_filtering` documentation below.
|
---|
| 102 |
|
---|
| 103 | Timeline
|
---|
| 104 | ++++++++
|
---|
| 105 |
|
---|
| 106 | You can get a *timeline* of all the stamped stamps::
|
---|
| 107 |
|
---|
| 108 | stamps -t
|
---|
| 109 |
|
---|
| 110 | This *timeline* will show each stamp in a line, in a similar way to what bebu's
|
---|
| 111 | stamp [1]_ stores in its text-based file::
|
---|
| 112 |
|
---|
| 113 | 2014-08-12 12:33 start
|
---|
| 114 | 2014-08-12 12:51 stamper writing installation instructions
|
---|
| 115 | 2014-08-12 13:11 stamper writing usage documentation
|
---|
| 116 | 2014-08-13 09:33 start
|
---|
| 117 | 2014-08-13 12:12 stamper adding missing tests for the cli tools
|
---|
| 118 |
|
---|
| 119 | You can filter the timeline by **ID**::
|
---|
| 120 |
|
---|
| 121 | stamps -t stamper
|
---|
| 122 |
|
---|
| 123 | And/or by date::
|
---|
| 124 |
|
---|
| 125 | stamps -t 2m
|
---|
| 126 |
|
---|
| 127 | .. seealso::
|
---|
| 128 |
|
---|
| 129 | *2m* is a date-based filter. You can learn more about those filters
|
---|
| 130 | in the :ref:`date_based_filtering` documentation below.
|
---|
| 131 |
|
---|
| 132 |
|
---|
| 133 |
|
---|
| 134 |
|
---|
| 135 | Full List of arguments
|
---|
| 136 | ++++++++++++++++++++++
|
---|
| 137 |
|
---|
| 138 | .. argparse::
|
---|
| 139 | :module: stamper.cli
|
---|
| 140 | :func: build_args_parser
|
---|
| 141 | :prog: stamper
|
---|
| 142 |
|
---|
| 143 |
|
---|
| 144 | .. _date_based_filtering:
|
---|
| 145 |
|
---|
| 146 | Date-based filtering
|
---|
| 147 | --------------------
|
---|
| 148 |
|
---|
| 149 | Most of the results returned by the *stamps* tool can be filtered using the
|
---|
| 150 | following date-based filters:
|
---|
| 151 |
|
---|
| 152 | - **YYYY-MM-DD**: Limit the results to only those stamps stamped on this date::
|
---|
| 153 |
|
---|
| 154 | stamps -v 2014-08-13
|
---|
| 155 |
|
---|
| 156 | ::
|
---|
| 157 |
|
---|
| 158 | stamps -t stamper 2014-08-13
|
---|
| 159 |
|
---|
| 160 | - **YYYY-MM-DD\***: Limit the results to only those stamps stamped **after this
|
---|
| 161 | date**. For example, this will show per-day details for stamps stamped after
|
---|
| 162 | the first of august, 2014::
|
---|
| 163 |
|
---|
| 164 | stamps -v 2014-08-01*
|
---|
| 165 |
|
---|
| 166 | - **\*YYYY-MM-DD**: Limit the results to only those stamps stamped **before this
|
---|
| 167 | date**. For example this will show the total time stamped for project stamper
|
---|
| 168 | before the first of january, 2014::
|
---|
| 169 |
|
---|
| 170 | stamps stamper *2014-01-01
|
---|
| 171 |
|
---|
| 172 | - **YYYY-MM-DD--YYYY-MM-DD**: Limit the results to only those stamps stamped in
|
---|
| 173 | a date **between those dates**. For example, this will show the *timeline* for
|
---|
| 174 | july, 2014::
|
---|
| 175 |
|
---|
| 176 | stamps -t 2014-07-01--2014-08-01
|
---|
| 177 |
|
---|
| 178 | - **nD|W|M|Y**: Limit the results to only those stamps stamped since n *days*
|
---|
| 179 | (**D**), *weeks* (**W**), *months* (**M**) or *years* (**Y**) ago.
|
---|
| 180 | For example, this will show the details for the last month::
|
---|
| 181 |
|
---|
| 182 | stamps -v 1m
|
---|
| 183 |
|
---|
| 184 | .. note::
|
---|
| 185 |
|
---|
| 186 | It does not matter if you provide *d|w|m|y* or *D|W|M|Y*. The filters are
|
---|
| 187 | handled in a case-insensitive way.
|
---|
| 188 |
|
---|
| 189 |
|
---|
| 190 | .. [1] http://repos.betabug.ch/stamp
|
---|