Open keith555 opened 2 years ago
SangamSwadiK
commented
2 years ago I think modification is needed here as well and the image, its confusing to beginners.
The working tree is a single checkout of one version of the project. These files are pulled out of the compressed database in the Git directory and placed on disk for you to use or modify.
I think working directory (speaking generally) is different than working tree.
keith555
commented
2 years ago I think in parts of the Git documentation the terms are used interchangeable, but in that particular page, which is aimed at people new to git the use of terminology is confusing.
The text introduces "_..the three main sections of a Git project: the working tree, the staging area, and the Git directory._". Out of nowhere, the diagram includes Working Directory which is inevitable going to be confusing to anyone not familiar with Git. They'll wonder whether it is a reference to the Working Tree, the Git Directory, or something else.
SangamSwadiK
commented
2 years ago I think in parts of the Git documentation the terms are used interchangeable, but in that particular page, which is aimed at people new to git the use of terminology is confusing.
The text introduces "_..the three main sections of a Git project: the working tree, the staging area, and the Git directory._". Out of nowhere, the diagram includes Working Directory which is inevitable going to be confusing to anyone not familiar with Git. They'll wonder whether it is a reference to the Working Tree, the Git Directory, or something else.
Agree 100%.
ben
commented
2 years ago Looks like we did some discussion of this way back in #1059, and probably some other times as well. My usual take on this topic is that "working tree" and "working directory" are used non-formally and interchangeably in chapter 2, because none of them have a hard technical definition (in the same way that, say, "commit" does). Not that the man pages are the final word on this, but they also use these terms sort of willy-nilly: ctrl-f for working directory and working tree.
Using all of them roughly interchangeably has a couple of benefits. It matches the conversational tone we want to keep in this chapter – this early in the book, the main audience is people who are fairly new to Git and maybe to command-line interfaces in general. It also introduces the concept that things can be called more than one thing in a casual setting, and since these two concepts are kind of mushy anyways, it's okay that we kind of mush them together.
Now worktree is an actual command, so if we're using that anywhere we should stop it right away. But I don't see a major problem with the other two phrases coexisting.
jlpoolen
commented
1 year ago Why not simply write "Working Tree" and "Working Directory" are being used here as simultaneous terms. I stumbled on this assumed dichotomy seeing Figure 6 and then scratching my head: did I miss something that equates these two terms? I'm at page 17 and I applaud your adherence to the practice of defining an acronym at its first instance, so many writers do not follow that rule, so it came as a surprise to me to find the use of two terms without an explicit association or assignment.
jlpoolen
commented
1 year ago Why not simply write "Working Tree" and "Working Directory" are being used here as simultaneous terms. I stumbled on this assumed dichotomy seeing Figure 6 and then scratching my head: did I miss something that equates these two terms? I'm at page 17 and I applaud your adherence to the practice of defining an acronym at its first instance, so many writers do not follow that rule, so it came as a surprise to me to find the use of two terms without an explicit association or assignment.
I think the section "The Three States" could be further refined. I slept on the concern I posted above and had an epiphany about the "states", if you will that could be further clarified in this section. I think at this point it is critical to differentiate between what files exist on the hard drive vs. what files are on what I'll call for the moment, the "Guest List" and which I think may be what is referred to as the "index". I think the reader should be able to understand the difference between files sitting in the hard drive directory vs. files that are on the Guest List. The subtle differences could be further illustrated. If you check out a project and visit one of the directories, there may be files a.txt, b.txt, and c.txt. These files were pulled out of git and placed in that directory. I you add to the directory a file named new.txt, you now have a discrepancy: the directory has 4 files, but the guest list only accounts for 3. So, at this point how would you describe the state of "Working tree" and "Staging area"? In the terminology I created, I would say that the hard drive directory is now out of sync with the Guest List as the hard drive directory has a file not on the Guest List. Likewise, if I deleted a.txt, the the hard drive directory would be further out of sync with the Guest List because Guest List is expecting a.txt to be present on the hard drive and in no longer is.
I think an understanding of this duality, files on the hard drive vs. Guest List, is critical at this juncture and a full understand of how the two can easily become out of sync will help the reader. Having "Working tree" and "Working Directory" can lead to confusion, I think. I'm not new to source control and I've just always felt I did not have a good understanding of git, so I decided to sit down and commit time to read this book. Having this epiphany at this early stage compels me to expound here in this Issue, especially since others seem to be tripped up, as well. I hope this is considered in the light I'm offering this suggestion.
jlpoolen
commented
1 year ago Why not simply write "Working Tree" and "Working Directory" are being used here as simultaneous terms. I stumbled on this assumed dichotomy seeing Figure 6 and then scratching my head: did I miss something that equates these two terms? I'm at page 17 and I applaud your adherence to the practice of defining an acronym at its first instance, so many writers do not follow that rule, so it came as a surprise to me to find the use of two terms without an explicit association or assignment.
I think the section "The Three States" could be further refined. I slept on the concern I posted above and had an epiphany about the "states", if you will that could be further clarified in this section. I think at this point it is critical to differentiate between what files exist on the hard drive vs. what files are on what I'll call for the moment, the "Guest List" and which I think may be what is referred to as the "index". I think the reader should be able to understand the difference between files sitting in the hard drive directory vs. files that are on the Guest List. The subtle differences could be further illustrated. If you check out a project and visit one of the directories, there may be files a.txt, b.txt, and c.txt. These files were pulled out of git and placed in that directory. I you add to the directory a file named new.txt, you now have a discrepancy: the directory has 4 files, but the guest list only accounts for 3. So, at this point how would you describe the state of "Working tree" and "Staging area"? In the terminology I created, I would say that the hard drive directory is now out of sync with the Guest List as the hard drive directory has a file not on the Guest List. Likewise, if I deleted a.txt, the the hard drive directory would be further out of sync with the Guest List because Guest List is expecting a.txt to be present on the hard drive and in no longer is.
I think an understanding of this duality, files on the hard drive vs. Guest List, is critical at this juncture and a full understand of how the two can easily become out of sync will help the reader. Having "Working tree" and "Working Directory" can lead to confusion, I think. I'm not new to source control and I've just always felt I did not have a good understanding of git, so I decided to sit down and commit time to read this book. Having this epiphany at this early stage compels me to expound here in this Issue, especially since others seem to be tripped up, as well. I hope this is considered in the light I'm offering this suggestion.
Perhaps the words causing confusing for me are "area" and "directory. I think of both of those terms as physical descriptions. And I further think you are trying to distinguish between a) what's in the git database, b) what's is listed on a manifest ("Guest List"), and c) what files resides in the operating system's directory structure. If you had "Staging Manifest", then I'd think of that middle state as a more ephemeral/conceptual state not to be confused with a directory listing.
jlpoolen
commented
1 year ago Why not simply write "Working Tree" and "Working Directory" are being used here as simultaneous terms. I stumbled on this assumed dichotomy seeing Figure 6 and then scratching my head: did I miss something that equates these two terms? I'm at page 17 and I applaud your adherence to the practice of defining an acronym at its first instance, so many writers do not follow that rule, so it came as a surprise to me to find the use of two terms without an explicit association or assignment.
I think the section "The Three States" could be further refined. I slept on the concern I posted above and had an epiphany about the "states", if you will that could be further clarified in this section. I think at this point it is critical to differentiate between what files exist on the hard drive vs. what files are on what I'll call for the moment, the "Guest List" and which I think may be what is referred to as the "index". I think the reader should be able to understand the difference between files sitting in the hard drive directory vs. files that are on the Guest List. The subtle differences could be further illustrated. If you check out a project and visit one of the directories, there may be files a.txt, b.txt, and c.txt. These files were pulled out of git and placed in that directory. I you add to the directory a file named new.txt, you now have a discrepancy: the directory has 4 files, but the guest list only accounts for 3. So, at this point how would you describe the state of "Working tree" and "Staging area"? In the terminology I created, I would say that the hard drive directory is now out of sync with the Guest List as the hard drive directory has a file not on the Guest List. Likewise, if I deleted a.txt, the the hard drive directory would be further out of sync with the Guest List because Guest List is expecting a.txt to be present on the hard drive and in no longer is. I think an understanding of this duality, files on the hard drive vs. Guest List, is critical at this juncture and a full understand of how the two can easily become out of sync will help the reader. Having "Working tree" and "Working Directory" can lead to confusion, I think. I'm not new to source control and I've just always felt I did not have a good understanding of git, so I decided to sit down and commit time to read this book. Having this epiphany at this early stage compels me to expound here in this Issue, especially since others seem to be tripped up, as well. I hope this is considered in the light I'm offering this suggestion.
Perhaps the words causing confusing for me are "area" and "directory. I think of both of those terms as physical descriptions. And I further think you are trying to distinguish between a) what's in the git database, b) what's is listed on a manifest ("Guest List"), and c) what files resides in the operating system's directory structure. If you had "Staging Manifest", then I'd think of that middle state as a more ephemeral/conceptual state not to be confused with a directory listing.
Dare I reference the Windows-centric Tortoise SVN Client which makes use of colored icons to indicate an actual file in the directory's status. Green checkmark indicates it matches the Guest List and has not been altered.. Question mark indicates the file is not on the Guest List. The user then has these visual queues to understand that the physical files are out of sync with what is expected or inventoried within Subversion'a manifest for that particular directory.
There's no existing/similar bug report.
This report is about a single actionable bug.
This report is about the ProGit book, version 2, English language.
Bug covers book website/pdf
Problem is present in the Pro Git book on the website?
Which version of the book is affected?
I don't know
Describe the bug:
Figure 6. Working tree, staging area, and Git directory in 1.3 Getting Started - What is Git? refers to the Working Tree as Working Directory.
Steps to reproduce:
Expected behavior:
The figure should be consistent with the caption and the explanatory text.
Screenshots:
No response
Additional context:
No response
Device
No response
Operating system
No response
Browser/application + version
No response