Re: [PATCH v2 4/4] doc: git-add: explain inconsistent terminology

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Evans <julia@jvns.ca>
>
> I think the fact that git uses these three terms interchangeably is
> extremely confusing and that it deserves to be noted.

We tend to avoid saying "I think" in our proposed log messages, as
we do not churn the code and documentation merely to match personal
preferences.

I do not necessarily think "git add --help" is an appropriate place
to leave this note, by the way.  We should start from teaching "git
help glossary", which does not mention "staging area" at all, which
is a sign that it is somewhat outdated.  It does not use the verb
'to stage' even once, either.

Here is my attempt to improve the situation by giving a definition
of "staging area" in the glossary.  Luckily, "cache" already has its
own entry, describing it as an old synonym to the 'index', so I
didn't have to do anything there.  Also the description of 'index'
has a bit too much implementation detail, which I toned down.

---
Subject: glossary: talk about "staging area"

Surprisingly, "git help glossary" does not mention the 'staging
area' synonym for the index, or the verb 'to stage'.  As "git
status" output uses the latter (i.e. "Changes not staged for
commit"), we should not leave it undefined what the verb means.

Rewrite the definition of the `index` somewhat to reduce the level
of implementation detail exposed, and focus more on the fact that it
is a mapping from pathnames to the contents at these paths.  And
mention the `staging area` there, as well as giving its own glossary
entry.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/glossary-content.adoc | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git c/Documentation/glossary-content.adoc w/Documentation/glossary-content.adoc
index e423e4765b..10f0c21e88 100644
--- c/Documentation/glossary-content.adoc
+++ w/Documentation/glossary-content.adoc
@@ -247,11 +247,15 @@ for a more flexible and robust system to do the same thing.
 	of Git you had to make them executable.
 
 [[def_index]]index::
-	A collection of files with stat information, whose contents are stored
-	as objects. The index is a stored version of your
-	<<def_working_tree,working tree>>. Truth be told, it can also contain a second, and even
-	a third version of a working tree, which are used
-	when <<def_merge,merging>>.
+	The index stores the mapping from filenames to their contents
+	to prepare the contents of the next commit by updating the
+	object recorded for each path (for this reason, people often
+	say that the index is "like the staging area" when explaining
+	the concept), together with other information to detect which
+	working tree files are modified efficiently.
+	During a conflicted <<def_merge,merge>>, the index can have
+	multiple versions of contents at higher stages for the same
+	path.
 
 [[def_index_entry]]index entry::
 	The information regarding a particular file, stored in the
@@ -650,6 +654,12 @@ the `refs/tags/` hierarchy is used to represent local tags..
 	is created by giving the `--depth` option to linkgit:git-clone[1], and
 	its history can be later deepened with linkgit:git-fetch[1].
 
+[[def_stage]]staging area::
+	A synonym for <<def_index,index>>.  Adding contents to the
+	index to update the mapping from the filename to its contents
+	is often called "to stage" (verb), as people explain the index
+	is like a staging area to prepare for the next commit.
+
 [[def_stash]]stash entry::
 	An <<def_object,object>> used to temporarily store the contents of a
 	<<def_dirty,dirty>> working directory and the index for future reuse.