view mercurial/help/dates.txt @ 23167:a3c2d9211294 stable

templater: don't overwrite the keyword mapping in runsymbol() (issue4362)

This keyword remapping was introduced in e06e9fd2d99f as part of converting
generator based iterators into list based iterators, mentioning "undesired
behavior in template" when a generator is exhausted, but doesn't say what and
introduces no tests.

The problem with the remapping was that it corrupted the output for keywords
like 'extras', 'file_copies' and 'file_copies_switch' in templates such as:

    $ hg log -r 142b5d5ec9cc --template "{file_copies % ' File: {file_copy}\n'}"
    File: mercurial/changelog.py (mercurial/hg.py)
    File: mercurial/changelog.py (mercurial/hg.py)
    File: mercurial/changelog.py (mercurial/hg.py)
    File: mercurial/changelog.py (mercurial/hg.py)
    File: mercurial/changelog.py (mercurial/hg.py)
    File: mercurial/changelog.py (mercurial/hg.py)
    File: mercurial/changelog.py (mercurial/hg.py)
    File: mercurial/changelog.py (mercurial/hg.py)

What was happening was that in the first call to runtemplate() inside runmap(),
'lm' mapped the keyword (e.g. file_copies) to the appropriate showxxx() method.
On each subsequent call to runtemplate() in that loop however, the keyword was
mapped to a list of the first item's pieces, e.g.:

   'file_copy': ['mercurial/changelog.py', ' (', 'mercurial/hg.py', ')']

Therefore, the dict for the second and any subsequent items were not processed
through the corresponding showxxx() method, and the first item's data was
reused.

The 'extras' keyword regressed in de7e6c489412, and 'file_copies' regressed in
0b241d7a8c62 for other reasons.  The common thread of things fixed by this seems
to be when a list of dicts are passed to the templatekw._hybrid class.

Some commands allow the user to specify a date, e.g.:

- backout, commit, import, tag: Specify the commit date.
- log, revert, update: Select revision(s) by date.

Many date formats are valid. Here are some examples:

- ``Wed Dec 6 13:18:29 2006`` (local timezone assumed)
- ``Dec 6 13:18 -0600`` (year assumed, time offset provided)
- ``Dec 6 13:18 UTC`` (UTC and GMT are aliases for +0000)
- ``Dec 6`` (midnight)
- ``13:18`` (today assumed)
- ``3:39`` (3:39AM assumed)
- ``3:39pm`` (15:39)
- ``2006-12-06 13:18:29`` (ISO 8601 format)
- ``2006-12-6 13:18``
- ``2006-12-6``
- ``12-6``
- ``12/6``
- ``12/6/6`` (Dec 6 2006)
- ``today`` (midnight)
- ``yesterday`` (midnight)
- ``now`` - right now

Lastly, there is Mercurial's internal format:

- ``1165411109 0`` (Wed Dec 6 13:18:29 2006 UTC)

This is the internal representation format for dates. The first number
is the number of seconds since the epoch (1970-01-01 00:00 UTC). The
second is the offset of the local timezone, in seconds west of UTC
(negative if the timezone is east of UTC).

The log command also accepts date ranges:

- ``<DATE`` - at or before a given date/time
- ``>DATE`` - on or after a given date/time
- ``DATE to DATE`` - a date range, inclusive
- ``-DAYS`` - within a given number of days of today