racy-git: documentation updates.
We've removed the workaround for runtime penalty that did not exist in practice some time ago, but the technical paper that proposed that change still said "we probably should do so". Signed-off-by: Junio C Hamano <junkio@cox.net>
Junio C Hamano committed
Dec 18, 2006 at 14:18 UTC
e1bb1d31ea7b5a2a3f20508e5643e8fc9ee5f0fd
1 file changed
+20
-18
Documentation/technical/racy-git.txt
+20
-18
@@ -4,7 +4,7 @@ Use of index and Racy git problem
4
Background
5
----------
6
7
-The index is one of the most important data structure in git.
7
+The index is one of the most important data structures in git.
8
It represents a virtual working tree state by recording list of
9
paths and their object names and serves as a staging area to
10
write out the next tree object to be committed. The state is
@@ -16,7 +16,7 @@ virtual working tree state in the index and the files in the
16
working tree. The most obvious case is when the user asks `git
17
diff` (or its low level implementation, `git diff-files`) or
18
`git-ls-files --modified`. In addition, git internally checks
19
-if the files in the working tree is different from what are
19
+if the files in the working tree are different from what are
20
recorded in the index to avoid stomping on local changes in them
21
during patch application, switching branches, and merging.
22
@@ -24,9 +24,9 @@ In order to speed up this comparison between the files in the
24
working tree and the index entries, the index entries record the
25
information obtained from the filesystem via `lstat(2)` system
26
call when they were last updated. When checking if they differ,
27
-git first runs `lstat(2)` on the files and compare the result
27
+git first runs `lstat(2)` on the files and compares the result
28
with this information (this is what was originally done by the
29
-`ce_match_stat()` function, which the current code does in
29
+`ce_match_stat()` function, but the current code does it in
30
`ce_match_stat_basic()` function). If some of these "cached
31
stat information" fields do not match, git can tell that the
32
files are modified without even looking at their contents.
@@ -53,8 +53,9 @@ Racy git
53
There is one slight problem with the optimization based on the
54
cached stat information. Consider this sequence:
55
56
+ : modify 'foo'
57
$ git update-index 'foo'
57
- : modify 'foo' in-place without changing its size
58
+ : modify 'foo' again, in-place, without changing its size
59
60
The first `update-index` computes the object name of the
61
contents of file `foo` and updates the index entry for `foo`
@@ -62,7 +63,8 @@ along with the `struct stat` information. If the modification
63
that follows it happens very fast so that the file's `st_mtime`
64
timestamp does not change, after this sequence, the cached stat
65
information the index entry records still exactly match what you
65
-can obtain from the filesystem, but the file `foo` is modified.
66
+would see in the filesystem, even though the file `foo` is now
67
+different.
68
This way, git can incorrectly think files in the working tree
69
are unmodified even though they actually are. This is called
70
the "racy git" problem (discovered by Pasky), and the entries
@@ -87,7 +89,7 @@ the stat information from updated paths, `st_mtime` timestamp of
89
it is usually the same as or newer than any of the paths the
90
index contains. And no matter how quick the modification that
91
follows `git update-index foo` finishes, the resulting
90
-`st_mtime` timestamp on `foo` cannot get the timestamp earlier
92
+`st_mtime` timestamp on `foo` cannot get a value earlier
93
than the index file. Therefore, index entries that can be
94
racily clean are limited to the ones that have the same
95
timestamp as the index file itself.
@@ -111,7 +113,7 @@ value, and falsely clean entry `foo` would not be caught by the
113
timestamp comparison check done with the former logic anymore.
114
The latter makes sure that the cached stat information for `foo`
115
would never match with the file in the working tree, so later
114
-checks by `ce_match_stat_basic()` would report the index entry
116
+checks by `ce_match_stat_basic()` would report that the index entry
117
does not match the file and git does not have to fall back on more
118
expensive `ce_modified_check_fs()`.
119
@@ -155,17 +157,16 @@ of the cached stat information.
157
Avoiding runtime penalty
158
------------------------
159
158
-In order to avoid the above runtime penalty, the recent "master"
159
-branch (post 1.4.2) has a code that makes sure the index file
160
-gets timestamp newer than the youngest files in the index when
160
+In order to avoid the above runtime penalty, post 1.4.2 git used
161
+to have a code that made sure the index file
162
+got timestamp newer than the youngest files in the index when
163
there are many young files with the same timestamp as the
164
resulting index file would otherwise would have by waiting
165
before finishing writing the index file out.
166
165
-I suspect that in practice the situation where many paths in the
166
-index are all racily clean is quite rare. The only code paths
167
-that can record recent timestamp for large number of paths I
168
-know of are:
167
+I suspected that in practice the situation where many paths in the
168
+index are all racily clean was quite rare. The only code paths
169
+that can record recent timestamp for large number of paths are:
170
171
. Initial `git add .` of a large project.
172
@@ -188,6 +189,7 @@ youngest file in the working tree. This means that in these
189
cases there actually will not be any racily clean entry in
190
the resulting index.
191
191
-So in summary I think we should not worry about avoiding the
192
-runtime penalty and get rid of the "wait before finishing
193
-writing" code out.
192
+Based on this discussion, the current code does not use the
193
+"workaround" to avoid the runtime penalty that does not exist in
194
+practice anymore. This was done with commit 0fc82cff on Aug 15,
195
+2006.