Alright, after the discussion on Friday I feel like I've got a better
handle on the subject, so I went ahead and tried to document the
intended behaviour.
I noticed that you seem to be moving toward putting new notes on the
wiki, so I wrote it in wiki format.
-Rick-
=Design: MTime Preservation=
Nearly every modern operating system associated a "modified time" with
each file on the system, updating it whenever the file is modified. This
metadata can be very important, but Subversion currently offers no way
to preserve it.
This design proposes two new properties:
; <nowiki>svn:text-time</nowiki>: This property stores the modified time
of each file or directory in UTC time using the format
'YYYY-MM-DDTHH:MM:SS.UUUUUU'. It is automatically generated by
Subversion during commit. The name of this property was chosen because
it is already used in an identical manner by FSVS and svntar.
; <nowiki>svn:use-text-times</nowiki>: The user defines this property on
a directory as a list of file types for which svn:text-time should be
applied. Its syntax is identical to svn:ignore.
==Definitions==
; mtime: Modified time. In this specification, mtime will always refer
to the modified time of a file as stored by the operating system. Under
this specification, Subversion will sometimes alter the mtime to equal
the value stored in svn:text-time.
; stime: System time. The current time according to the operating system
at the time of the operation in question; aka now().
; ctime: Commit time. The timestamp currently stored by Subversion
indicating when the file or directory was committed.
==Interaction with use-commit-times==
Wherever use-commit-times conflicts with this specification,
use-commit-times takes precedence. This will be defined in more detail
in the following operations.
==Operations==
* Any operations not listed are presumed to be unaffected by this proposal.
* For the sake of being succinct, 'svn:' will be elided from
'svn:text-time' and 'svn:use-text-times' in the following operations.
* use-commit-times is used here as a boolean variable. It is true if
the user has set use-commit-times=yes in their configuration.
* The operations below apply to individual files or directories. For
operations that support multiple nodes, the operation is simply repeated
for each node.
===svn commit===
* If use-text-times matches and (mtime differs from text-time or
text-time is undefined), text-time = mtime
===svn checkout===
* If use-commit-times, mtime = ctime
* Else if use-text-times matches and text-time is defined, mtime = text-time
* Else, mtime = stime
===svn update===
* If use-commit-times, mtime = ctime
* Else if use-text-times matches:
** If local modifications exist, mtime = stime and text-time is deleted.
** (This is to prevent mtime-only conflicts; text-time will be reapplied
in the next commit.)
** Else if text-time is defined, mtime = text-time
* Else, mtime = stime
===svn merge===
* If no conflicts occur, behaviour is identical to svn update.
* Else if use-text-times matches, mtime=stime and text-time is deleted.
** (This is to avoid mtime-only conflicts; on commit, text-time will be
reapplied.)
===svn resolve===
* The rules above should ensure that, if a conflict occurred, the
text-time property was deleted.
* If (resolved with base, mine-full, or theirs-full) and the file chosen
has text-time defined, text-time is copied and mtime=text-time.
===svn copy===
text-time is not copied.
===svn rename===
* mtime is unchanged.
* text-time is preserved.
* (This may not be possible until true-renames are supported. Until that
tile, treating a rename as a copy+delete is acceptable.)
==Setting and Comparing Dates==
Not all operating systems can support the resolution of the
svn:text-time format specified. When setting mtime, the time should
always be rounded down to the nearest supported resolution first. When
comparing mtime against text-time, text-time should always be rounded
down first.
==Use cases==
===Control cases===
These are cases that Subversion is currently used for, and are expected
to continue to work identically.
====make====
The build system 'make' defines a specific set of output files for a
specific set of input files. Whenever the output files are built, their
mtime is set to stime. Whenever rebuilding, it checks to see if mtime of
the the input files is newer than the mtime of the output files and
rebuilds them if that's the case.
For this case to work, the output files must not be under version
control, and use-text-times must not match the input files.
====Log files====
Log files are often opened and resaved, even when nothing is written to
them. This is not expected to count as a modification.
For this case to work, use-text-times must not match the log files.
====Compiler-generated files====
When building software, the compiler may be configured to output a
compiler-generated file. These often get re-generated with identical
output, only modifying the mtime. This is not expected to count as a
modification.
For this case to work, use-text-times must not match the output files.
To reduce the number of unnecessary generations, it also should not
match the input files.
===Motivating use cases===
These are some of the reasons that users require this feature.
====Image compression====
In this scenario, the user stores uncompressed images in one folder and
then runs a script to compress the images and dump them in another
folder. The compression tool can generate slightly different bitstreams
on different computers. Both folders are required to be under version
control, and should avoid recompressing images that have not changed.
For this case to work, use-text-times must match both the input and
output files. The script must also set the mtime of each output file to
the mtime of the matching input file and only recompress when the mtimes
differ.
====Subversion as a backup tool====
In this scenario, Subversion is primarily used to detect modified files
and upload them to an off-site server; version control is only used in
rare cases, such as a file being backup up after it was corrupted.
For this case to work, use-text-times should be set to * recursively.
All unversioned files must be added whenever committing, and unversioned
directories must also have their use-text-times property set to *. The
latter step could be eliminated if something similar to Issue #1054
(Specify default properties on a per repository or per directory basis)
is implemented.
====Finding documents by publication date====
Some users maintain their mtime to refer to the publication date of a
file. It should be possible to locate a document based on its mtime,
even if that document was committed weeks after it was modified.
For this case to work, use-text-times must match the document types. In
an unmixed-environment, matching '*' would be sufficient.
====Web server====
Web servers expose the mtime as the 'Last-Modified-Date' header in http
requests, which is used in a variety of ways. Clients use it to
determine whether or not the file needs to be re-cached, reducing
bandwidth for the server. Search engines use it to determine if the page
needs to be reindexed, or when the user requests to find a page matching
a certain date range. Users use it when they need to determine if the
information on a page is obsolete. Web servers also offer index pages,
which show all the files in a directory and allow the user to sort by mtime.
For this to work, use-text-times must match the documents. Web sites are
often a mixed-environment, so some file types may have to be left out of
use-text-times to ensure tools like 'make' function properly.
==References==
* [http://subversion.tigris.org/issues/show_bug.cgi?id=1256 Issue 1256:
Ability to preserve last modification time (mtime) of files under
version control]
* [http://svn.haxx.se/dev/archive-2012-02/0440.shtml @dev discussion]
* [http://svn.haxx.se/dev/archive-2010-02/0127.shtml Previous proposal
by Edmund Wong]
* [http://subversion.tigris.org/issues/show_bug.cgi?id=1054 Issue 1054:
Specify default properties on a per repository or per directory basis]
Received on 2012-02-20 11:06:33 CET