hledger/hledger-lib/hledger_timedot.txt

hledger_timedot(5)           hledger User Manuals           hledger_timedot(5)



NAME
       Timedot - hledger's human-friendly time logging format

DESCRIPTION
       Timedot  is  a plain text format for logging dated, categorised quanti-
       ties (of time, usually), supported by hledger.  It  is  convenient  for
       approximate  and retroactive time logging, eg when the real-time clock-
       in/out required with a timeclock file is too precise or  too  interrup-
       tive.   It  can be formatted like a bar chart, making clear at a glance
       where time was spent.

       Though called "timedot", this format is read by hledger  as  commodity-
       less  quantities,  so  it  could  be used to represent dated quantities
       other than time.  In the docs below we'll assume it's time.

       A timedot file contains a series of day entries.  A  day  entry  begins
       with  a  non-indented hledger-style simple date (Y-M-D, Y/M/D, Y.M.D..)
       Any additional text on the same line is used as a transaction  descrip-
       tion for this day.

       This is followed by optionally-indented timelog items for that day, one
       per line.  Each timelog item is a  note,  usually  a  hledger:style:ac-
       count:name  representing  a time category, followed by two or more spa-
       ces, and a quantity.  Each timelog item generates  a  hledger  transac-
       tion.

       Quantities can be written as:

       o dots:  a sequence of dots (.) representing quarter hours.  Spaces may
         optionally be used for grouping.  Eg: ....  ..

       o an integral or decimal number, representing hours.  Eg: 1.5

       o an integral or decimal number immediately followed by a  unit  symbol
         s,  m,  h, d, w, mo, or y, representing seconds, minutes, hours, days
         weeks, months or years respectively.  Eg: 90m.  The following equiva-
         lencies  are  assumed,  currently: 1m = 60s, 1h = 60m, 1d = 24h, 1w =
         7d, 1mo = 30d, 1y=365d.

       There is some flexibility allowing notes and  todo  lists  to  be  kept
       right in the time log, if needed:

       o Blank lines and lines beginning with # or ; are ignored.

       o Lines not ending with a double-space and quantity are parsed as items
         taking no time, which will not appear in balance reports by  default.
         (Add -E to see them.)

       o Org  mode headlines (lines beginning with one or more * followed by a
         space) can be used as date lines or timelog items (the stars are  ig-
         nored).   Also  all  org headlines before the first date line are ig-
         nored.  This means org users can manage their timelog as an org  out-
         line  (eg  using org-mode/orgstruct-mode in Emacs), for organisation,
         faster navigation, controlling visibility etc.

       Examples:

              # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
              2016/2/1
              inc:client1   .... .... .... .... .... ....
              fos:haskell   .... ..
              biz:research  .

              2016/2/2
              inc:client1   .... ....
              biz:research  .

              2016/2/3
              inc:client1   4
              fos:hledger   3
              biz:research  1

              * Time log
              ** 2020-01-01
              *** adm:time  .
              *** adm:finance  .

              * 2020 Work Diary
              ** Q1
              *** 2020-02-29
              **** DONE
              0700 yoga
              **** UNPLANNED
              **** BEGUN
              hom:chores
               cleaning  ...
               water plants
                outdoor - one full watering can
                indoor - light watering
              **** TODO
              adm:planning: trip
              *** LATER

       Reporting:

              $ hledger -f t.timedot print date:2016/2/2
              2016-02-02 *
                  (inc:client1)          2.00

              2016-02-02 *
                  (biz:research)          0.25

              $ hledger -f t.timedot bal --daily --tree
              Balance changes in 2016-02-01-2016-02-03:

                          ||  2016-02-01d  2016-02-02d  2016-02-03d
              ============++========================================
               biz        ||         0.25         0.25         1.00
                 research ||         0.25         0.25         1.00
               fos        ||         1.50            0         3.00
                 haskell  ||         1.50            0            0
                 hledger  ||            0            0         3.00
               inc        ||         6.00         2.00         4.00
                 client1  ||         6.00         2.00         4.00
              ------------++----------------------------------------
                          ||         7.75         2.25         8.00

       I prefer to use period for separating account components.  We can  make
       this work with an account alias:

              2016/2/4
              fos.hledger.timedot  4
              fos.ledger           ..

              $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4
                              4.50  fos
                              4.00    hledger:timedot
                              0.50    ledger
              --------------------
                              4.50

       Here is a sample.timedot.



REPORTING BUGS
       Report  bugs at http://bugs.hledger.org (or on the #hledger IRC channel
       or hledger mail list)


AUTHORS
       Simon Michael <simon@joyful.com> and contributors


COPYRIGHT
       Copyright (C) 2007-2019 Simon Michael.
       Released under GNU GPL v3 or later.


SEE ALSO
       hledger(1),     hledger-ui(1),     hledger-web(1),      hledger-api(1),
       hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
       dot(5), ledger(1)

       http://hledger.org



hledger 1.17                      March 2020                hledger_timedot(5)