Git: What is exactly a 'working tree'? Is the same as 'working directory'?

Question

I am reading lots of documentation about Git and recently I have been looking for "working tree" concept, but I don't understand what exactly a "working tree" is.

I have found this description: What is a working tree? that seems to be the easiest to understand. But I don't fully understand it.

In the link I can read:

The Working Tree in Git is a directory (and its files and subdirectories) on your file system

So as far I can understand, the working tree is a folder on my computer. Right? Which folder exactly?

The explanation follows...

that is associated with a repository.

The term repository in the explanation is refering to the local repository as anyone can see in the following picture (the blue-green rectangle)?

Looking for similar questions here, in stackoverflow, I have found this: Working tree vs working directory

The second answer, answered by Greg, says:

Working tree means the directory that contains the .git folder, including all sub directories and files.

So I understand that working tree is the same as the working directory. Right? I mean, the directory I have the source code of my project, for example C:\Richard\Projects\Calc\ that is where I execute the command git init (inside \Calc).

Is my understanding correct?

Answer 1

The offical glossary defines a working tree as:

The tree of actual checked out files.
The working tree normally contains the contents of the HEAD commit’s tree, plus any local changes that you have made but not yet committed.

It does not mention "working directory".

I mean, the directory I have the source code of my project, for example C:\Richard\Projects\Calc\ that is where I execute the command git init (inside \Calc).

Not always.

A working tree does not always have a .git in it:

• either because the environment variable GIT_DIR is set (and references the actual path of the .git subfolder, which can be anywhere else)

• or because you have used the git worktree command, which allows you to checkout multiple branches in multiple separate working directories, from one cloned repository: see "Multiple working directories with Git?".

But, as illustrated by that last command, "working directory" is used as a synonym from "working tree".

The second is preferred: in the very beginning of Git, commit 2a29da7 (Git v0.99.5, Aug. 2005), Junio C. Hamano mentioned:

Use "working tree", "object name", "repository" as the canonical term consistently.

---

"working tree" and "per-worktree ref" were in glossary, but "worktree" itself wasn't, which has been corrected with Git 2.36 (Q2 2022).

See commit 2df5387 (09 Feb 2022) by Junio C Hamano (gitster).
^{(Merged by Junio C Hamano -- gitster -- in commit 9a1d169, 18 Feb 2022)}

glossary: describe "worktree"

We have description on "per worktree ref", but "worktree" is not described in the glossary.
We do have "working tree", though.

Casually put, a "working tree" is what your editor and compiler interacts with.
"worktree" is a mechanism to allow one or more "working tree"s to be attached to a repository and used to check out different commits and branches independently, which includes not just a "working tree" but also repository metadata like HEAD, the index to support simultaneous use of them.
Historically, we used these terms interchangeably but we have been trying to use "working tree" when we mean it, instead of "worktree".

Most of the existing references to "working tree" in the glossary do refer primarily to the working tree portion, except for one that said refs like HEAD and refs/bisect/* are per "working tree", but it is more precise to say they are per "worktree".

glossary-content now includes in its man page:

worktree

A repository can have zero (i.e. bare repository) or one or more worktrees attached to it. One "worktree" consists of a "working tree" and repository metadata, most of which are shared among other worktrees of a single repository, and some of which are maintained separately per worktree (e.g. the index, HEAD and pseudorefs like MERGE_HEAD, per-worktree refs and per-worktree configuration file).

---

So, Git 2.36 (Q2 2022) tightens the language around "working tree" and "worktree" in the docs.

See commit 07d8538, commit f13a146, commit 7b21582, commit a777d4c, commit 6036be1, commit 5997014, commit c57bf8c, commit 23f832e, commit ace5ac5, commit 8639705, commit 92d9234 (23 Feb 2022) by Derrick Stolee (derrickstolee).
^{(Merged by Junio C Hamano -- gitster -- in commit aae90a1, 06 Mar 2022)}

worktree: use 'worktree' over 'working tree'

^{Signed-off-by: Derrick Stolee}

It is helpful to distinguish between a 'working tree' and a 'worktree'.
A worktree contains a working tree plus additional metadata.
This metadata includes per-worktree refs and worktree-specific config.

This is the sixth of multiple changes to git-worktree.txt, restricted to the DETAILS section.

git worktree now includes in its man page:

Each linked worktree has a private sub-directory in the repository's
...
the base name of the linked worktree's path, possibly appended with a
...