3

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)? enter image description here

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?

Richard Steele
  • 95
  • 1
  • 10
  • "Yes" is too short for a comment :-) *Working tree* is the new name, but both refer to the same thing. – Romain Valeri Nov 28 '19 at 15:37
  • @RomainValeri I think they both refer to the same thing, but there is a subtle difference: the term "tree" and the term "directory", right? Directory is a single thing, a folder. The term tree refers also to a single thing: the file-folder structure, right?. So directory refers to a physical thing: a folder, the term tree refers to a specific structure (an inmaterial thing, a way of classifying thing, a type. a kind of), but both are speaking about the same thing. – Richard Steele Nov 28 '19 at 15:43
  • 1
    The difference you're pointing to is real, but it's between "directory" and "tree" in and of themselves, in their general sense in computer science. In git's specific context, these expressions do refer to the same thing, at least in the practical sense. – Romain Valeri Nov 28 '19 at 15:54
  • I think it is more related to the way they are called in svn and git. in git it's called _working tree_. In svn it's _working copy_ . – eftshift0 Nov 28 '19 at 16:32
  • @eftshift0 Thanks, what is svn? subversion? – Richard Steele Nov 28 '19 at 19:23
  • Yes, that's right, – eftshift0 Nov 28 '19 at 19:25

1 Answers1

4

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:

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
...

VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • Thank you! So, is it correct this definition (working tree): "The Working Tree in Git is a directory (and its files and subdirectories) on your file system that is associated with a repository." Understanding "repository" as all the three folders (working directory, staging area and commit history). – Richard Steele Nov 28 '19 at 20:58
  • 1
    @RichardSteele Yes, that seems coherent with how Git does work. – VonC Nov 28 '19 at 21:22
  • 1
    @RichardSteele That being said, the official definition: https://git-scm.com/docs/gitglossary#def_working_tree: where the files are checked out. – VonC Nov 28 '19 at 21:23