CODEWITHSUNDEEP
gitgit-indexgit-stage
Marecky
Marecky

Reputation: 2096

Why does the "git index" have so many names?

While reading how to use Git, I found a lot of different names for git index.

They were:

How come there are so many options to name exactly one thing?

How I should to name it to not to confuse my future interlocutors whose backgrounds I do not know?

Upvotes: 5

Views: 287

Answers (3)

VonC
VonC

Reputation: 1324537

With Git 2.30.1 (Q1 2021), the documentation is now clearer regarding "index" synonyms based on "cache": they are obsolete and purged from said documentation.

See commit b356d23 (08 Jan 2021) by Utku Gultopu (ugultopu).
(Merged by Junio C Hamano -- gitster -- in commit eecc5f0, 15 Jan 2021)

doc: remove "directory cache" from man pages

Signed-off-by: Utku Gultopu

"directory cache" (or "directory cache index", "cache") are obsolete terms which have been superseded by "index".
Keeping them in the documentation may be a source of confusion.
This commit replaces them with the current term, "index", on man pages.

git ls-files now includes in its man page:

This merges the file listing in the index with the actual working directory list, and shows different combinations of the two.

git update-index now includes in its man page:

Modifies the index.
Each file mentioned is updated into the index and any 'unmerged' or 'needs updating' state is cleared.

Upvotes: 3

Jonathan.Brink
Jonathan.Brink

Reputation: 25393

I agree with @Harmelodic ... the term "Staging area" is probably most used and straight-forward.

For example, when using the git-add command, you can say that you are "staging" content.

The term index was used early on in Git's development but it was changed.

This is a good historical thread.

Snippits:

Commands that pay attention to the registered content of files rather than the copies in the work tree use the option name "--cached". This is mostly for historical reasons --- early on, it was not obvious that making the index not match the worktree was going to be useful.

...

"cache" was an old name (and still established name in-use in the code) for the index...cached to mean "look only at what is recorded in the index".

...

Originally, the way to say "what is in the current working tree for this path is what I want to have in the next commit" was "update-index". "What I want to have in the next commit" is "the index", and the operation is about "updating" that "What I want to have...", so the name of the command made perfect sense. "update-index" had a safety valve to prevent careless invocation of "update-index *" to add all the cruft in the working tree (there wasn't any .gitignore mechanism in the Porcelain nor in the plumbing) and by default affected only the paths that are already in the index. You needed to say "update-index --add" to include paths that are not in the index.

A more user friendly Porcelain "git add" was later implemented in terms of "update-index --add", but originally it was to add new paths; updating the contents was still done via "update-index" interface.

...

In short, "stage" is an unessential synonym that came much later

Upvotes: 4

Harmelodic
Harmelodic

Reputation: 6139

From my experience, the most commonly used term is Staging Area.

Evidence:

  • Files and folders are referred to as Staged and Unstaged in the Git system when performing git commands.
  • From what I've observed: Most developers only read the Getting Started - Git Basics documentation when first starting out with Git. This document refers to it as the Staging Area.
  • As someone who works a lot with Git and often surrounded by people who work a lot with it to, most developers I've met refer to it as the Staging Area.

Upvotes: 2

Related Questions