Source

TimeStampMod / README.rst

TimeStampMod

About (version 0.1.5 beta)

TimeStampMod is an extension for Mercurial DVCS that incorporates automatic saving and restoring of the modification times of files under version control. This extension is based on an original timestamp extension by Friedrich Kastner- Masilko <face@snoopie.at> hosted at https://bitbucket.org/face/timestamp.

The intent of this extension is to ease the transition from manual file system based version control into the Mercurial DVCS world. Typically, manual file system based version control methods rely on copying and synchronizing files centered around file modification timestamp information. Under any modern VCS, this timestamp information is regarded as unimportant since the VCS manages all of the revision tracking between revision records. This means that the default behavior of most VCS is to set the file modification time to the time that the file was updated by the VCS instead of the original modification time. This is a behavior that can be confusing and lead to mistrust of the VCS by new users who are not yet familiar with VCS concepts.

Incorporating automatic timestamp saving and restoring into an extension allows Mercurial to add an extra level of comfort to those users who are more familiar with manually managing their version control via traditional file management.

Requirements

This extension was developed for use with the following:

Note that only Mercurial is required for the use of this extension. However, there are some peculiarities in the code specific to use with TortoiseHg. It may also be worth noting that this extension was developed and tested only on Windows XP SP3, so functionality under other operating systems my not be one- hundred-percent reliable.

Installation

Begin by downloading the TimestampMod.py file and saving it on your computer. A typical location for the file would be in an "Extensions" under the TortoiseHg program folder (usually "C:Program FilesTortoiseHg"). Note that this is not a default folder in the TortoiseHg installation, and must be added manually.

Then edit the appropriate configuration file:

  • The global configuration file - either:
  1. mercurial.ini for TortoiseHg, or
  2. hgrc for a stand-alone Mercurial installation.
  • Each individual repository configuration file (.hg\hgrc) where the extension is to be used.

Add an entry into the extensions section of the configuration file similar to the following:

[extensions]
TimestampMod = /path/to/TimestampMod.py

If using TortoiseHg, some of the hooks will need to be manually configured. Add entries into the hooks section of the configuration file (mercurial.ini) similar to the following:

[hooks]
post-merge.TimestampMod = python:/path/to/TimestampMod.py:Hook_Post_Merge
post-resolve.TimestampMod = python:/path/to/TimestampMod.py:Hook_Post_Resolve
post-revert.TimestampMod = python:/path/to/TimestampMod.py:Hook_Post_Revert

Nothing further is required to make the extension work. It will set up it's own hooks that will trigger during committing and updating actions automatically.

For advanced users:

Optionally, if using the extension from TortoiseHg's installation of Mercurial, the extension can be installed by compiling the TimestampMod.py Python code into its TimestampMod.pyo compiled form and inserting it into TortoiseHg's library.zip file. This eliminates the need to specify a path when enabling the extensions, and the extension will show up in TortoiseHg's configuration dialogs.

The simplest way to compile it for your version is to:
  1. Install it normally as described above.
  2. Run a 'hg timestamp_mod --help' command to verify that it is installed correctly.
  3. Copy the resulting TimestampMod.pyo file into the root of the library.zip file.

This is only recommended if you have experience with manipulating the library.zip file for TortoiseHg.

!!! Known Issues !!!

Every attempt is made to keep this extension up-to-date and in working order, but there are occasional problems that arise in the development process. These issues will be noted here, and possible work-around recommendations provided if at all possible.

  • Support has been added for restoring timestamps of individual files or groups of files when the "Revert" command is used. This features works well using Mercurial directly (command-line), but does not work at all for most TortoiseHg menu command and dialogs. As of TortoiseHg 2.2.2, there is an outstanding issue with how the "Revert" command has been implemented within TortiseHg that does not allow it to take advantage of the hooks from extensions like this one. Currently (TortoiseHg 2.2.2), the only command that seems to work from TortoiseHg is the Windows Explorer context menu "TortiseHg > Revert Files..." item.
  • Because the timestamp record file is modified on every commit, there are nearly always merge conflicts with the timestamp file. Most of the time, these are trivial and can be resolved with a simple "Tool Resolve" option. Manually resolving the differences is not too difficult either. Just keep in mind that a larger timestamp number means a newer timestamp. This issue can affect any commands that involve merging such as graft or import (when dealing with patches). No further work will be done on this issue. After spending much time imagining how this could be automated, it was decided that it is best left to the user to determine the most appropriate timestamps to keep when merging the timestamp file.

Further Reading

If you are not familiar with installing extensions for Mercurial/TortoiseHg, it is strongly recommended to review the UsingExtensions wiki page from Mercurial. The wiki documents the basic use of extensions, as well as provides links to additional extensions that you may find useful.

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.