← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/cache.py

  • Committer: Martin Pool
  • Date: 2005-05-10 04:50:12 UTC
  • Revision ID: mbp@sourcefrog.net-20050510045012-b48422ffc2187699
- statcache docs

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/cache.py
20
20
from trace import mutter
21
21
 
22
22
 
23
 
# file fingerprints are: (path, size, mtime, ctime, ino, dev).
24
 
#
25
 
# if this is the same for this file as in the previous revision, we
26
 
# assume the content is the same and the SHA-1 is the same.
27
 
 
28
 
# This is stored in a fingerprint file that also contains the file-id
29
 
# and the content SHA-1.
30
 
 
31
 
# Thus for any given file we can quickly get the SHA-1, either from
32
 
# the cache or if the cache is out of date.
33
 
 
34
 
# At the moment this is stored in a simple textfile; it might be nice
35
 
# to use a tdb instead.
36
 
 
37
 
 
38
 
# What we need:
39
 
 
40
 
# build a new cache from scratch
41
 
# load cache, incrementally update it
42
 
 
43
 
# TODO: Have a paranoid mode where we always compare the texts and
44
 
# always recalculate the digest, to trap modification without stat
45
 
# change and SHA collisions.
 
23
"""File stat cache to speed up tree comparisons.
 
24
 
 
25
This module basically gives a quick way to find the SHA-1 and related
 
26
information of a file in the working directory, without actually
 
27
reading and hashing the whole file.
 
28
 
 
29
This is done by maintaining a cache indexed by a file fingerprint of
 
30
(path, size, mtime, ctime, ino, dev) pointing to the SHA-1.  If the
 
31
fingerprint has changed, we assume the file content has not changed
 
32
either and the SHA-1 is therefore the same.
 
33
 
 
34
If any of the fingerprint fields have changed then the file content
 
35
*may* have changed, or it may not have.  We need to reread the file
 
36
contents to make sure, but this is not visible to the user or
 
37
higher-level code (except as a delay of course).
 
38
 
 
39
The mtime and ctime are stored with nanosecond fields, but not all
 
40
filesystems give this level of precision.  There is therefore a
 
41
possible race: the file might be modified twice within a second
 
42
without changing the size or mtime, and a SHA-1 cached from the first
 
43
version would be wrong.  We handle this by not recording a cached hash
 
44
for any files which were modified in the current second and that
 
45
therefore have the chance to change again before the second is up.
 
46
 
 
47
The only known hole in this design is if the system clock jumps
 
48
backwards crossing invocations of bzr.  Please don't do that; use ntp
 
49
to gradually adjust your clock or don't use bzr over the step.
 
50
 
 
51
At the moment this is stored in a simple textfile; it might be nice
 
52
to use a tdb instead.
 
53
"""
46
54
 
47
55
 
48
56