#pragma section-numbers 2
= Untouch Extension =
Save or restore modification times of files.

<<TableOfContents>>

== Status ==
'''This extension is not distributed with Mercurial.'''

''Author: '' ''[[http://michael.platin.gs/|Michael Platings]]''

Repository: [[http://bitbucket.org/mplatings/hg-untouch/]]

== Overview ==

For users of languages such as C++ that can have long compilation times, a fairly major irritation of Mercurial is the following scenario:
 * You make a change in a widely included header file.
 * To ensure that you haven't broken anything, you run make and wait for an hour while everything rebuilds.
 * There are no new build errors so you commit the change.
 * Before you can push, you must {{{hg pull --rebase}}} or {{{hg update}}} and {{{hg merge}}}.
 * Several new changesets are pulled so you run make again to make sure your change hasn't broken them.
 * Except Mercurial has touched the header you changed so now you've got to wait for another hour while make runs, even though none of the changesets you pulled are related to the header.
 * In that hour you waited for make to run again, more changesets have been added so now you're stuck in an infinite loop of pull and make.

The untouch extension remedies this problem by saving and restoring file modification times.

This extension can be used in 3 ways:

 1. When running {{{hg pull}}} with the {{{--rebase}}} option and without any resulting conflicts.

 The extension will automatically restore file modified times without any user input.

 Example:{{{
 hg pull --rebase
 }}}
 2. To explicitly save file modified times and later restore them.

 Running {{{hg untouch --save}}} will record the modified times of files in the working directory whose status is "added" or "modified" as well as files that are modified by ancestor changesets whose phase is "draft" or "secret".
  
 Running {{{hg untouch}}} will restore the modified times recorded by previously running {{{hg untouch --save}}}.

 Example:{{{
 hg untouch --save
 hg update tip
 hg merge
 hg commit -m "merge"
 hg untouch
 }}}
 3. Any time after running {{{hg pull}}}

 The user may run {{{hg untouch --prepull}}} to restore the modified times of certain files. The files will be those that were modified by ancestor changesets whose phase was "draft" or "secret" at the time {{{hg pull}}} was run.

 The prepull modified times are independent of those created by {{{hg untouch --save}}} so {{{hg untouch --prepull}}} can be used independently of {{{hg untouch}}}.

 Example:{{{
 hg pull
 hg update
 hg merge
 hg commit -m "merge"
 hg untouch --prepull
 }}}

The extension will never change the modified time of a file if it finds that the file's content has changed since its modified time was recorded.

== Configuration ==
Configure your ''`.hgrc`'' to enable the extension by adding following lines:

{{{
[extensions]
untouch = path/to/untouch.py
[hooks]
pre-pull.untouch = python:path/to/untouch.py:hook_pre_pull
post-pull.untouch = python:path/to/untouch.py:hook_post_pull
}}}

== See also ==

 * [[QtimesExtension|The qtimes extension]] is similar but focussed on files affected by patch queues only.

----
CategoryExtensionsByOthers