@matheusbsbs / matheus-bagliano / commits / 1c097891e4
Fork 0

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