# hgdate mercurial extension ## Contents * [Overview](#markdown-header-overview) * [Installation](#markdown-header-installation) * [Commands](#markdown-header-commands) * [Config Values](#markdown-header-config-values) * [Recent Activity](#repo-activity) ## 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: :::console $ 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](https://bitbucket.org/bmearns/hgdate/src/tip/hgext?at=default) directory to your system, and edit your hgrc config file to add the `hgdate.py` file as an extension: :::cfg [extensions] hgdate = /path/to/hgdate/hgext/hgdate.py You can just as well clone the entire [hgdate repository](https://bitbucket.org/bmearns/hgdate/) 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: :::console $ 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"](http://www.selenic.com/mercurial/hg.1.html#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: :::console $ 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: :::console $ hg date -v Date offset: None Repo time: Tue Oct 29 21:51:16 2013 -0400 Or, if the offset has been configured: :::console $ 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: :::console $ hg date --clear Date cleared Or, in more detail: :::console $ 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: :::cfg [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).