← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/dirstate.txt

  • Committer: Martin Pool
  • Date: 2005-04-28 07:24:55 UTC
  • Revision ID: mbp@sourcefrog.net-20050428072453-7b99afa993a1e549
todo

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/dirstate.txt
1
 
Dirstate
2
 
========
3
 
 
4
 
Don't really need the hashes of the current versions - just knowing
5
 
whether they've changed or not will generally be enough - and just the
6
 
mtime and ctime of a point in time may be enough?
7
 
 
8
 
 
9
 
``_dirblock_state``
10
 
-------------------
11
 
 
12
 
There are currently 4 levels that state can have.
13
 
 
14
 
 1. NOT_IN_MEMORY
15
 
    The actual content blocks have not been read at all.
16
 
 2. IN_MEMORY_UNMODIFIED
17
 
    The content blocks have been read and are available for use. They have
18
 
    not been changed at all versus what was written on disk when we read
19
 
    them.
20
 
 3. IN_MEMORY_HASH_MODIFIED
21
 
    We have updated the in-memory state, but only to record the
22
 
    sha1/symlink target value and the stat value that means this
23
 
    information is 'fresh'.
24
 
 4. IN_MEMORY_MODIFIED
25
 
    We have updated an actual record. (Parent lists, added a new file,
26
 
    deleted something, etc.) In this state, we must always write out the
27
 
    dirstate, or some user action will be lost.
28
 
 
29
 
 
30
 
IN_MEMORY_HASH_MODIFIED
31
 
~~~~~~~~~~~~~~~~~~~~~~~
32
 
 
33
 
This state is a bit special, so deserves its own topic.  If we are
34
 
IN_MEMORY_HASH_MODIFIED, we only write out the dirstate if enough records
35
 
have been updated. The idea is that if we would save future I/O by writing
36
 
an updated dirstate, then we should do so. The threshold for this is set
37
 
by "worth_saving_limit". The default is that at least 10 entries must be
38
 
updated in order to consider the dirstate file worth updating.
39
 
 
40
 
Going one step further, newly added files, symlinks, and directory entries
41
 
updates are treated specially. We know that we will always stat all
42
 
entries in the tree so that we can observe *if* they have changed. In the
43
 
case of directories, all the information we know about them is just from
44
 
that stat value. There is no extra content to read. So an update directory
45
 
entry doesn't cause us to update to IN_MEMORY_HASH_MODIFIED. However, if
46
 
there are other modifications worth saving, we will go ahead and save the
47
 
directory entry update at the same time.
48
 
 
49
 
Similarly, symlink targets are commonly stored in the inode entry
50
 
directly. So once we have stat'ed the symlink, we already have its target
51
 
information in memory. The one caveat is if we used to think an object was
52
 
a file, and it became a directory or symlink, then we will treat it as
53
 
worth saving.
54
 
 
55
 
In the case of newly added files, we never have to read their content to
56
 
know that they are different from the basis tree. So saving the updated
57
 
information also won't save a future read.
58
 
 
59
 
 
60
 
.. vim: ft=rst tw=74 et