Re: Consistent terminology: cached/staged/index

[Jonathan Nieder <jrnieder@gmail.com>]

Hi,

Felipe Contreras wrote:
[out of order for convenience]

> Why should the users care about the stat() information? Or how the
> merge conflicts are being tracked?

The second question is very easy to answer (depending on what "how"
means, of course).  Because people integrating changes from multiple
places need to be able to resolve a conflicted merge.

> That's plumbing, not porcelain.

I don't disagree.  The analogy is almost perfect.

And the thing is, in the real world, people know about plumbing.  They
don't care about the details, but they know there are these things
called pipes, and that water tends to flow downward, and that if one
of them freezes, it will burst.  This knowledge is useful.

Likewise, it is useful to know:

 - After you use "cp -a" to copy a repository, the first operation
   you perform is going to be slower.  The cached stat() information
   is stale.

 - Until you run "git add", there is only one copy of your data, in
   the worktree.  After you run "git add", there are two copies.
   Once you run "git commit", that second copy will last at least
   as long as your commit does.

   So there is some chance of recovery from fat-finger mistakes,
   even before a commit.

 - During a merge, you can mark your progress by collapsing index
   entries with 'git add'.  "git diff" will show the state of the
   merge.  You can read the competing versions of a file with
   "git show :2:path/to/file" and "git show :3:path/to/file".

 - Index-only operations tend to be faster, since

    (1) the cached blobs are not changing, so we can save time
        stat(2)-ing and read(2)-ing files
    (2) blobs are compressed: less I/O.  Longstanding blobs are
        in pack files: good caching and I/O patterns.

   So you can speed up your slow "git grep" by using
   "git grep --cached".

 - When scripting, you can use a temporary index file to avoid
   affecting the remembered worktree state.

But so what?  I have nothing against clearer terms.  I am just saying
that (1) we should be explaining these things somewhere and (2) a
global s/index/only one of the things the index does/ is a bad idea,
because it would make the documentation *wrong*.

> There's always resistance, but 1.8 is supposed to contain stuff as "if
> git was written from scratch".

I thought 1.8 was supposed to provide an opportunity to correct some
long-known mistakes that we had been holding back on for backward
compatibility reasons.  That doesn't mean we should forget the cost of
change.

Thanks for your work, and hope that helps.
Jonathan