user-manual: rewrite index discussion
Add an example using git-ls-files, standardize on the new "index" terminology (as opposed to "cache"), attempt to clarify discussion and make it a little shorter, avoid some unnecessary jargon ("write-back cache"). Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
J. Bruce Fields committed
Sep 3, 2007 at 12:59 UTC
1c097891e49042cf7ee4628a58836625fb65016d
1 file changed
+55
-49
Documentation/user-manual.txt
+55
-49
@@ -2911,57 +2911,63 @@ gitlink:git-verify-tag[1].
2911
2912
2913
[[the-index]]
2914
-The "index" aka "Current Directory Cache"
2915
------------------------------------------
2914
+The index
2915
+-----------
2916
+
2917
+The index is a binary file (generally kept in .git/index) containing a
2918
+sorted list of path names, each with permissions and the SHA1 of a blob
2919
+object; gitlink:git-ls-files[1] can show you the contents of the index:
2920
2917
-The index is a simple binary file, which contains an efficient
2918
-representation of the contents of a virtual directory. It
2919
-does so by a simple array that associates a set of names, dates,
2920
-permissions and content (aka "blob") objects together. The cache is
2921
-always kept ordered by name, and names are unique (with a few very
2922
-specific rules) at any point in time, but the cache has no long-term
2923
-meaning, and can be partially updated at any time.
2924
-
2925
-In particular, the index certainly does not need to be consistent with
2926
-the current directory contents (in fact, most operations will depend on
2927
-different ways to make the index 'not' be consistent with the directory
2928
-hierarchy), but it has three very important attributes:
2929
-
2930
-'(a) it can re-generate the full state it caches (not just the
2931
-directory structure: it contains pointers to the "blob" objects so
2932
-that it can regenerate the data too)'
2933
-
2934
-As a special case, there is a clear and unambiguous one-way mapping
2935
-from a current directory cache to a "tree object", which can be
2936
-efficiently created from just the current directory cache without
2937
-actually looking at any other data. So a directory cache at any one
2938
-time uniquely specifies one and only one "tree" object (but has
2939
-additional data to make it easy to match up that tree object with what
2940
-has happened in the directory)
2941
-
2942
-'(b) it has efficient methods for finding inconsistencies between that
2943
-cached state ("tree object waiting to be instantiated") and the
2944
-current state.'
2945
-
2946
-'(c) it can additionally efficiently represent information about merge
2947
-conflicts between different tree objects, allowing each pathname to be
2921
+-------------------------------------------------
2922
+$ git ls-files --stage
2923
+100644 63c918c667fa005ff12ad89437f2fdc80926e21c 0 .gitignore
2924
+100644 5529b198e8d14decbe4ad99db3f7fb632de0439d 0 .mailmap
2925
+100644 6ff87c4664981e4397625791c8ea3bbb5f2279a3 0 COPYING
2926
+100644 a37b2152bd26be2c2289e1f57a292534a51a93c7 0 Documentation/.gitignore
2927
+100644 fbefe9a45b00a54b58d94d06eca48b03d40a50e0 0 Documentation/Makefile
2928
+...
2929
+100644 2511aef8d89ab52be5ec6a5e46236b4b6bcd07ea 0 xdiff/xtypes.h
2930
+100644 2ade97b2574a9f77e7ae4002a4e07a6a38e46d07 0 xdiff/xutils.c
2931
+100644 d5de8292e05e7c36c4b68857c1cf9855e3d2f70a 0 xdiff/xutils.h
2932
+-------------------------------------------------
2933
+
2934
+Note that in older documentation you may see the index called the
2935
+"current directory cache" or just the "cache". It has three important
2936
+properties:
2937
+
2938
+1. The index contains all the information necessary to generate a single
2939
+(uniquely determined) tree object.
2940
++
2941
+For example, running gitlink:git-commit[1] generates this tree object
2942
+from the index, stores it in the object database, and uses it as the
2943
+tree object associated with the new commit.
2944
+
2945
+2. The index enables fast comparisons between the tree object it defines
2946
+and the working tree.
2947
++
2948
+It does this by storing some additional data for each entry (such as
2949
+the last modified time). This data is not displayed above, and is not
2950
+stored in the created tree object, but it can be used to determine
2951
+quickly which files in the working directory differ from what was
2952
+stored in the index, and thus save git from having to read all of the
2953
+data from such files to look for changes.
2954
+
2955
+3. It can efficiently represent information about merge conflicts
2956
+between different tree objects, allowing each pathname to be
2957
associated with sufficient information about the trees involved that
2949
-you can create a three-way merge between them.'
2950
-
2951
-Those are the ONLY three things that the directory cache does. It's a
2952
-cache, and the normal operation is to re-generate it completely from a
2953
-known tree object, or update/compare it with a live tree that is being
2954
-developed. If you blow the directory cache away entirely, you generally
2955
-haven't lost any information as long as you have the name of the tree
2956
-that it described.
2957
-
2958
-At the same time, the index is also the staging area for creating
2959
-new trees, and creating a new tree always involves a controlled
2960
-modification of the index file. In particular, the index file can
2961
-have the representation of an intermediate tree that has not yet been
2962
-instantiated. So the index can be thought of as a write-back cache,
2963
-which can contain dirty information that has not yet been written back
2964
-to the backing store.
2958
+you can create a three-way merge between them.
2959
++
2960
+We saw in <<conflict-resolution>> that during a merge the index can
2961
+store multiple versions of a single file (called "stages"). The third
2962
+column in the gitlink:git-ls-files[1] output above is the stage
2963
+number, and will take on values other than 0 for files with merge
2964
+conflicts.
2965
+
2966
+The index is thus a sort of temporary staging area, which is filled with
2967
+a tree which you are in the process of working on.
2968
+
2969
+If you blow the index away entirely, you generally haven't lost any
2970
+information as long as you have the name of the tree that it described.
2971
2972
[[low-level-operations]]
2973
Low-level git operations