Source

hgdate /

Filename Size Date modified Message
hgext
60 B
7.5 KB
267 B

hgdate mercurial extension

Contents

Overview

The hgdate extension for mercurial allows you to set a persistent date offset in your repository which gets applied to commits. This is similar in concept to the --date option on the commit command, but instead of specifying it on each commit, you just specify a reference date once and the extension manages it from there.

A simple example may be illustrative:

$ date
Mon Oct 28 20:00:00 EDT 2013
$ 
$ # Set a date reference
$ hg date "Oct 22 1984"
Repo date set: Mon Oct 22 00:00:00 1984 -0400

$ #edit some files
$ date
Mon Oct 28 20:30:00 EDT 2013
$ # 30 minutes have elapsed
$
$ hg ci
$ hg log
changeset:   0:2f0b7f53d6e1
tag:         tip
user:        bmearns
date:        Mon Oct 22 00:30:00 1984 -0400


$ #edit some more files
$ date
Mon Oct 28 21:15:00 EDT 2013
$ # Another 45 minutes have elapsed, 1h15m since hg date was set.
$
$ hg ci
$ hg log
changeset:   1:a92497e622e9
tag:         tip
user:        bmearns
date:        Mon Oct 22 01:15:00 1984 -0400

changeset:   0:2f0b7f53d6e1
user:        bmearns
date:        Mon Oct 22 00:30:00 1984 -0400

In this example, we've set the repository's reference date to midnight on 22 October 1984. After thirty minutes of editing, we commit, and the time stamp for the commit is thirty minutes past midnight on 22 October 1984. We work for another forty-five minutes, and then commit again and the time stamp is forty-five minutes later, 1:15 AM on 22 October 1984.

You'll have to use your imagination to come up with some scenarios in which this would be useful.

Installation

To install this extension, download the files in the hgext directory to your system, and edit your hgrc config file to add the hgdate.py file as an extension:

[extensions]
hgdate = /path/to/hgdate/hgext/hgdate.py

You can just as well clone the entire hgdate repository and use it the same way, just make sure you point the extension at the hgdate.py file.

It doesn't matter where you place the files, but a common place to put them is under ~/.hgext (on Windows, this would be %HOMEDRIVE%%HOMEPATH%\.hgext, typically C:\Users\USERNAME\.hgext in Windows 7).

Dependencies

To use the extension, you also need to have the hgconfig extension installed and enabled. You can get hgconfig from https://bitbucket.org/alu/hgconfig/, and install/enable it in the same way as describe above (except point to the config.py file for this extension).

Commands

hg date

The extension provides a new function, hg date, which can be used to both set and query the date offset for the repository.

Usage:

hg date [options] [ --clear | DATE ]

Options:

-c, --clear Clear the date offset for the repository.
-R, --repository ROOT Specify the root directory for the repository to act on.
-v, --verbose Enable additional output.
-h, --help Display help for the function and exit.

Details:

Set offset

When invoked with the DATE argument, the command sets the repository's date offset such that the current time is considered as the specified DATE, according to the repository. For example:

$ hg date "Oct 22 1984"
Repo date set: Mon Oct 22 00:00:00 1984 -0400

Acceptable formats for the DATE argument are any that mercurial itself can recognize. Here are some examples of acceptable dates:

Dec 29 1984 Set to midnight (localtime) on the specified date.
Dec 29 Same as above, assumes current year.
Dec 29 5:55 Specify a date and local time. Time is in 24-hour format by default, so this is 5:55 AM.
Dec 29 5:55 UTC Specify a time in UTC.
13:54:47 Specify a time on the current day.
1:54:47pm Specify AM or PM.
yesterday midnight yesterday (local time)
today midnight today (local time)

For details on date formats, see "Date Formats" section of the hg man page.

Query offset

When invoked with neither the --clear option nor the DATE argument, the function simply prints out the current date and time, according to the repository and the currently configured date offset. If no date offset is set for the repository, this will be equal to the current time according to the computer system. For example:

$ hg date
Repo time: Tue Oct 29 21:51:16 2013 -0400

If you pass the --verbose option, the configured offset is also printed. For example:

$ hg date -v
Date offset: None
Repo time: Tue Oct 29 21:51:16 2013 -0400

Or, if the offset has been configured:

$ hg date -v
Date offset: 10599 days, 21:54:40 (past)
Repo time: Mon Oct 22 00:00:02 1984 -0400
Clear Offset

To get rid of the offset and get your repository back to using real time, simply pass the --clear option. For example:

$ hg date --clear
Date cleared

Or, in more detail:

$ hg date "Oct 22 1984"
Repo date set: Mon Oct 22 00:00:00 1984 -0400

$ hg date
Repo time: Mon Oct 22 00:00:19 1984 -0400

$ hg date --clear
Date cleared

$ hg date
Repo time: Tue Oct 29 21:58:11 2013 -0400

Config Values

The hgdate extension stores and loads the repository's offset in the hgdate.offset config value. The offset is stored as an integer number of seconds. If no such config value is found or is invalid, no offset is used.

When you set the offset with the hg date DATE command, the resulting offset is written to the config file, overwriting the current value if present.

The extension will load a value from any config file on the search path, with the lowest config file which has it set winning (just like all other config values). However, when storing a value, it will only ever write to the repository's config file (i.g., .hg/hgrc under the repository's root directory).

You can manually edit this config value, but since it's a somewhat opaque value, this is not generally recommended. If you do edit it, remember that this is an offset (in seconds) not an actual date value. Positive values indicate a time in the future, negative values are in the past (because the offset is added to the real time to get the repository time).

For example:

[hgdate]
offset = -18000

This configuration sets the offset such that repository times with be five hours in the past (60 seconds per minute times 60 minutes per hour times 5 hours).