* [PATCH v1 2/3] Documentation: your checkout directory is "working tree" (part 1)
2025-11-11 19:58 [PATCH v1 0/3] War on "work tree" Junio C Hamano
2025-11-11 19:58 ` [PATCH v1 1/3] notes doc: call NOTES_MERGE_WORKTREE a "worktree", not " Junio C Hamano
@ 2025-11-11 19:58 ` Junio C Hamano
2025-11-12 6:41 ` Patrick Steinhardt
2025-11-11 19:58 ` [PATCH v1 3/3] Documentation: your checkout directory is "working tree" (part 2) Junio C Hamano
2 siblings, 1 reply; 5+ messages in thread
From: Junio C Hamano @ 2025-11-11 19:58 UTC (permalink / raw)
To: git
As "git help glossary" says, there is "working tree" that is a
directory that holds a checkout, and there is "worktree" (one word)
that is a working tree plus repository metadata. There is no "work
tree".
Many of these documentation pages that use the phrase "work tree"
were written way before the "worktree" mechanism was introduced, and
they talk about what we call "working tree" these days.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
Documentation/diff-format.adoc | 2 +-
Documentation/diff-options.adoc | 2 +-
Documentation/git-add.adoc | 2 +-
Documentation/git-grep.adoc | 2 +-
Documentation/git-hash-object.adoc | 2 +-
Documentation/git-read-tree.adoc | 14 +++++++-------
Documentation/git-rev-parse.adoc | 4 ++--
Documentation/git-rm.adoc | 4 ++--
Documentation/git-stash.adoc | 2 +-
Documentation/git-status.adoc | 14 +++++++-------
Documentation/git-submodule.adoc | 2 +-
Documentation/gitattributes.adoc | 16 ++++++++--------
Documentation/gitcli.adoc | 10 +++++-----
Documentation/gitmodules.adoc | 2 +-
Documentation/user-manual.adoc | 8 ++++----
15 files changed, 43 insertions(+), 43 deletions(-)
diff --git a/Documentation/diff-format.adoc b/Documentation/diff-format.adoc
index 9f7e988241..6b1f9c2124 100644
--- a/Documentation/diff-format.adoc
+++ b/Documentation/diff-format.adoc
@@ -43,7 +43,7 @@ That is, from the left to the right:
. a space.
. sha1 for "src"; 0\{40\} if creation or unmerged.
. a space.
-. sha1 for "dst"; 0\{40\} if deletion, unmerged or "work tree out of sync with the index".
+. sha1 for "dst"; 0\{40\} if deletion, unmerged or "working tree file out of sync with the index".
. a space.
. status, followed by optional "score" number.
. a tab or a NUL when `-z` option is used.
diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc
index ae31520f7f..cb623a0c7d 100644
--- a/Documentation/diff-options.adoc
+++ b/Documentation/diff-options.adoc
@@ -864,7 +864,7 @@ endif::git-format-patch[]
`ignore` option in linkgit:git-config[1] or linkgit:gitmodules[5]. When
`untracked` is used submodules are not considered dirty when they only
contain untracked content (but they are still scanned for modified
- content). Using `dirty` ignores all changes to the work tree of submodules,
+ content). Using `dirty` ignores all changes to the working tree of submodules,
only changes to the commits stored in the superproject are shown (this was
the behavior until 1.7.0). Using `all` hides all changes to submodules.
diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
index 6192daeb03..18e7ed9b79 100644
--- a/Documentation/git-add.adoc
+++ b/Documentation/git-add.adoc
@@ -94,7 +94,7 @@ in linkgit:gitglossary[7].
`-p`::
`--patch`::
Interactively choose hunks of patch between the index and the
- work tree and add them to the index. This gives the user a chance
+ working tree and add them to the index. This gives the user a chance
to review the difference before adding modified contents to the
index.
+
diff --git a/Documentation/git-grep.adoc b/Documentation/git-grep.adoc
index a548585d4c..5be258f1cd 100644
--- a/Documentation/git-grep.adoc
+++ b/Documentation/git-grep.adoc
@@ -33,7 +33,7 @@ SYNOPSIS
DESCRIPTION
-----------
-Look for specified patterns in the tracked files in the work tree, blobs
+Look for specified patterns in the tracked files in the working tree, blobs
registered in the index file, or blobs in given tree objects. Patterns
are lists of one or more search expressions separated by newline
characters. An empty string as search expression matches all lines.
diff --git a/Documentation/git-hash-object.adoc b/Documentation/git-hash-object.adoc
index ef4719ae41..0a02f77004 100644
--- a/Documentation/git-hash-object.adoc
+++ b/Documentation/git-hash-object.adoc
@@ -17,7 +17,7 @@ DESCRIPTION
-----------
Computes the object ID value for an object with specified type
with the contents of the named file (which can be outside of the
-work tree), and optionally writes the resulting object into the
+working tree), and optionally writes the resulting object into the
object database. Reports its object ID to its standard output.
When <type> is not specified, it defaults to "blob".
diff --git a/Documentation/git-read-tree.adoc b/Documentation/git-read-tree.adoc
index 1c04bba2b7..9d60badd74 100644
--- a/Documentation/git-read-tree.adoc
+++ b/Documentation/git-read-tree.adoc
@@ -23,7 +23,7 @@ linkgit:git-checkout-index[1])
Optionally, it can merge a tree into the index, perform a
fast-forward (i.e. 2-way) merge, or a 3-way merge, with the `-m`
flag. When used with `-m`, the `-u` flag causes it to also update
-the files in the work tree with the result of the merge.
+the files in the working tree with the result of the merge.
Only trivial merges are done by 'git read-tree' itself. Only conflicting paths
will be in an unmerged state when 'git read-tree' returns.
@@ -158,7 +158,7 @@ fast-forward situation).
When two trees are specified, the user is telling 'git read-tree'
the following:
- 1. The current index and work tree is derived from $H, but
+ 1. The current index and working tree is derived from $H, but
the user may have local changes in them since $H.
2. The user wants to fast-forward to $M.
@@ -166,7 +166,7 @@ the following:
In this case, the `git read-tree -m $H $M` command makes sure
that no local change is lost as the result of this "merge".
Here are the "carry forward" rules, where "I" denotes the index,
-"clean" means that index and work tree coincide, and "exists"/"nothing"
+"clean" means that index and working tree coincide, and "exists"/"nothing"
refer to the presence of a path in the specified commit:
....
@@ -212,7 +212,7 @@ refer to the presence of a path in the specified commit:
In all "keep index" cases, the index entry stays as in the
original index file. If the entry is not up to date,
-'git read-tree' keeps the copy in the work tree intact when
+'git read-tree' keeps the copy in the working tree intact when
operating under the -u flag.
When this form of 'git read-tree' returns successfully, you can
@@ -317,7 +317,7 @@ end of a successful merge.
When you start a 3-way merge with an index file that is already
populated, it is assumed that it represents the state of the
-files in your work tree, and you can even have files with
+files in your working tree, and you can even have files with
changes unrecorded in the index file. It is further assumed
that this state is "derived" from the stage 2 tree. The 3-way
merge refuses to run if it finds an entry in the original index
@@ -342,7 +342,7 @@ $ git fetch git://.... linus
$ LT=`git rev-parse FETCH_HEAD`
----------------
-Your work tree is still based on your HEAD ($JC), but you have
+Your working tree is still based on your HEAD ($JC), but you have
some edits since. Three-way merge makes sure that you have not
added or modified index entries since $JC, and if you haven't,
then does the right thing. So with the following sequence:
@@ -355,7 +355,7 @@ $ echo "Merge with Linus" | \
----------------
what you would commit is a pure merge between $JC and $LT without
-your work-in-progress changes, and your work tree would be
+your work-in-progress changes, and your working tree would be
updated to the result of the merge.
However, if you have local changes in the working tree that
diff --git a/Documentation/git-rev-parse.adoc b/Documentation/git-rev-parse.adoc
index 5398691f3f..ced73fa8af 100644
--- a/Documentation/git-rev-parse.adoc
+++ b/Documentation/git-rev-parse.adoc
@@ -261,7 +261,7 @@ The following options are modified by `--path-format`:
relative to the current working directory.
+
If `$GIT_DIR` is not defined and the current directory
-is not detected to lie in a Git repository or work tree
+is not detected to lie in a Git repository or a working tree,
print a message to stderr and exit with nonzero status.
--git-common-dir::
@@ -305,7 +305,7 @@ The following options are unaffected by `--path-format`:
directory print "true", otherwise "false".
--is-inside-work-tree::
- When the current working directory is inside the work tree of the
+ When the current working directory is inside the working tree of the
repository print "true", otherwise "false".
--is-bare-repository::
diff --git a/Documentation/git-rm.adoc b/Documentation/git-rm.adoc
index b5ead86796..a7a3068381 100644
--- a/Documentation/git-rm.adoc
+++ b/Documentation/git-rm.adoc
@@ -163,12 +163,12 @@ will be staged (unless `--cached` or `-n` are used).
A submodule is considered up to date when the `HEAD` is the same as
recorded in the index, no tracked files are modified and no untracked
-files that aren't ignored are present in the submodule's work tree.
+files that aren't ignored are present in the submodule's working tree.
Ignored files are deemed expendable and won't stop a submodule's work
tree from being removed.
If you only want to remove the local checkout of a submodule from your
-work tree without committing the removal, use linkgit:git-submodule[1] `deinit`
+working tree without committing the removal, use linkgit:git-submodule[1] `deinit`
instead. Also see linkgit:gitsubmodules[7] for details on submodule removal.
EXAMPLES
diff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc
index 235d57ddd8..78de244390 100644
--- a/Documentation/git-stash.adoc
+++ b/Documentation/git-stash.adoc
@@ -365,7 +365,7 @@ $ git stash pop
Testing partial commits::
You can use `git stash push --keep-index` when you want to make two or
-more commits out of the changes in the work tree, and you want to test
+more commits out of the changes in the working tree, and you want to test
each change before committing:
+
----------------------------------------------------------------
diff --git a/Documentation/git-status.adoc b/Documentation/git-status.adoc
index 9a376886a5..b32db372cd 100644
--- a/Documentation/git-status.adoc
+++ b/Documentation/git-status.adoc
@@ -95,7 +95,7 @@ configuration variable documented in linkgit:git-config[1].
'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When
"untracked" is used submodules are not considered dirty when they only
contain untracked content (but they are still scanned for modified
- content). Using "dirty" ignores all changes to the work tree of submodules,
+ content). Using "dirty" ignores all changes to the working tree of submodules,
only changes to the commits stored in the superproject are shown (this was
the behavior before 1.7.0). Using "all" hides all changes to submodules
(and suppresses the output of submodule summaries when the config option
@@ -226,12 +226,12 @@ A [ MTD] added to index
D deleted from index
R [ MTD] renamed in index
C [ MTD] copied in index
-[MTARC] index and work tree matches
-[ MTARC] M work tree changed since index
-[ MTARC] T type changed in work tree since index
-[ MTARC] D deleted in work tree
- R renamed in work tree
- C copied in work tree
+[MTARC] index and working tree matches
+[ MTARC] M working tree changed since index
+[ MTARC] T type changed in working tree since index
+[ MTARC] D deleted in working tree
+ R renamed in working tree
+ C copied in working tree
-------------------------------------------------
D D unmerged, both deleted
A U unmerged, added by us
diff --git a/Documentation/git-submodule.adoc b/Documentation/git-submodule.adoc
index 95beaee561..bdba17d166 100644
--- a/Documentation/git-submodule.adoc
+++ b/Documentation/git-submodule.adoc
@@ -93,7 +93,7 @@ submodules, and show their status as well.
If you are only interested in changes of the currently initialized
submodules with respect to the commit recorded in the index or the HEAD,
linkgit:git-status[1] and linkgit:git-diff[1] will provide that information
-too (and can also report changes to a submodule's work tree).
+too (and can also report changes to a submodule's working tree).
init [--] [<path>...]::
Initialize the submodules recorded in the index (which were
diff --git a/Documentation/gitattributes.adoc b/Documentation/gitattributes.adoc
index f20041a323..39822c42ce 100644
--- a/Documentation/gitattributes.adoc
+++ b/Documentation/gitattributes.adoc
@@ -71,12 +71,12 @@ When deciding what attributes are assigned to a path, Git
consults `$GIT_DIR/info/attributes` file (which has the highest
precedence), `.gitattributes` file in the same directory as the
path in question, and its parent directories up to the toplevel of the
-work tree (the further the directory that contains `.gitattributes`
+working tree (the further the directory that contains `.gitattributes`
is from the path in question, the lower its precedence). Finally
global and system-wide files are considered (they have the lowest
precedence).
-When the `.gitattributes` file is missing from the work tree, the
+When the `.gitattributes` file is missing from the working tree, the
path in the index is used as a fall-back. During checkout process,
`.gitattributes` in the index is used and then the file in the
working tree is used as a fall-back.
@@ -286,18 +286,18 @@ the conversion is reversible for the current setting of
`core.autocrlf`. For "true", Git rejects irreversible
conversions; for "warn", Git only prints a warning but accepts
an irreversible conversion. The safety triggers to prevent such
-a conversion done to the files in the work tree, but there are a
+a conversion done to the files in the working tree, but there are a
few exceptions. Even though...
-- 'git add' itself does not touch the files in the work tree, the
+- 'git add' itself does not touch the files in the working tree, the
next checkout would, so the safety triggers;
- 'git apply' to update a text file with a patch does touch the files
- in the work tree, but the operation is about text files and CRLF
+ in the working tree, but the operation is about text files and CRLF
conversion is about fixing the line ending inconsistencies, so the
safety does not trigger;
-- 'git diff' itself does not touch the files in the work tree, it is
+- 'git diff' itself does not touch the files in the working tree, it is
often run to inspect the changes you intend to next 'git add'. To
catch potential problems early, safety triggers.
@@ -1115,7 +1115,7 @@ text::
binary::
- Keep the version from your branch in the work tree, but
+ Keep the version from your branch in the working tree, but
leave the path in the conflicted state for the user to
sort out.
@@ -1180,7 +1180,7 @@ using `%S`, `%X` and `%Y` respectively.
^^^^^^^^^^^^^^^^^^^^^^
This attribute controls the length of conflict markers left in
-the work tree file during a conflicted merge. Only a positive
+the working tree file during a conflicted merge. Only a positive
integer has a meaningful effect.
For example, this line in `.gitattributes` can be used to tell the merge
diff --git a/Documentation/gitcli.adoc b/Documentation/gitcli.adoc
index 6815d6bfb7..db88e84aaf 100644
--- a/Documentation/gitcli.adoc
+++ b/Documentation/gitcli.adoc
@@ -37,13 +37,13 @@ arguments. Here are the rules:
they can be disambiguated by placing `--` between them.
E.g. `git diff -- HEAD` is, "I have a file called HEAD in my work
tree. Please show changes between the version I staged in the index
- and what I have in the work tree for that file", not "show the difference
- between the HEAD commit and the work tree as a whole". You can say
+ and what I have in the working tree for that file", not "show the difference
+ between the HEAD commit and the working tree as a whole". You can say
`git diff HEAD --` to ask for the latter.
* Without disambiguating `--`, Git makes a reasonable guess, but errors
out and asks you to disambiguate when ambiguous. E.g. if you have a
- file called HEAD in your work tree, `git diff HEAD` is ambiguous, and
+ file called HEAD in your working tree, `git diff HEAD` is ambiguous, and
you have to say either `git diff HEAD --` or `git diff -- HEAD` to
disambiguate.
@@ -100,9 +100,9 @@ scripting Git:
them do.
* When you give a revision parameter to a command, make sure the parameter is
- not ambiguous with a name of a file in the work tree. E.g. do not write
+ not ambiguous with a name of a file in the working tree. E.g. do not write
`git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work
- if you happen to have a file called `HEAD` in the work tree.
+ if you happen to have a file called `HEAD` in the working tree.
* Many commands allow a long option `--option` to be abbreviated
only to their unique prefix (e.g. if there is no other option
diff --git a/Documentation/gitmodules.adoc b/Documentation/gitmodules.adoc
index d9bec8b187..464f24be9b 100644
--- a/Documentation/gitmodules.adoc
+++ b/Documentation/gitmodules.adoc
@@ -72,7 +72,7 @@ submodule.<name>.ignore::
nonetheless show up in the output of status and commit when it has
been staged).
- dirty;; All changes to the submodule's work tree will be ignored, only
+ dirty;; All changes to the submodule's working tree will be ignored, only
committed differences between the `HEAD` of the submodule and its
recorded state in the superproject are taken into account.
diff --git a/Documentation/user-manual.adoc b/Documentation/user-manual.adoc
index 7696987117..4b0aaef6a4 100644
--- a/Documentation/user-manual.adoc
+++ b/Documentation/user-manual.adoc
@@ -1188,7 +1188,7 @@ branch.
A merge is made by combining the changes made in `branchname` and the
changes made up to the latest commit in your current branch since
-their histories forked. The work tree is overwritten by the result of
+their histories forked. The working tree is overwritten by the result of
the merge when this combining is done cleanly, or overwritten by a
half-merged results when this combining results in conflicts.
Therefore, if you have uncommitted changes touching the same files as
@@ -1299,7 +1299,7 @@ $ git show :3:file.txt # the version from MERGE_HEAD.
-------------------------------------------------
When you ask linkgit:git-diff[1] to show the conflicts, it runs a
-three-way diff between the conflicted merge results in the work tree with
+three-way diff between the conflicted merge results in the working tree with
stages 2 and 3 to show only hunks whose contents come from both sides,
mixed (in other words, when a hunk's merge results come only from stage 2,
that part is not conflicting and is not shown. Same for stage 3).
@@ -2149,7 +2149,7 @@ He uses two public branches:
He also uses a set of temporary branches ("topic branches"), each
containing a logical grouping of patches.
-To set this up, first create your work tree by cloning Linus's public
+To set this up, first create your working tree by cloning Linus's public
tree:
-------------------------------------------------
@@ -3667,7 +3667,7 @@ files in a submodule, which silently leads to similar problems as not pushing
the submodule changes. Starting with Git 1.7.0 both `git status` and `git diff`
in the superproject show submodules as modified when they contain new or
modified files to protect against accidentally committing such a state. `git
-diff` will also add a `-dirty` to the work tree side when generating patch
+diff` will also add a `-dirty` to the working tree side when generating patch
output or used with the `--submodule` option:
-------------------------------------------------
--
2.52.0-rc1-455-g30608eb744
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH v1 3/3] Documentation: your checkout directory is "working tree" (part 2)
2025-11-11 19:58 [PATCH v1 0/3] War on "work tree" Junio C Hamano
2025-11-11 19:58 ` [PATCH v1 1/3] notes doc: call NOTES_MERGE_WORKTREE a "worktree", not " Junio C Hamano
2025-11-11 19:58 ` [PATCH v1 2/3] Documentation: your checkout directory is "working tree" (part 1) Junio C Hamano
@ 2025-11-11 19:58 ` Junio C Hamano
2 siblings, 0 replies; 5+ messages in thread
From: Junio C Hamano @ 2025-11-11 19:58 UTC (permalink / raw)
To: git
The same fix as the previous step, which replaced "work tree" with
"working tree" where appropriate, but this batch addresses the two
word phrase that are split across lines.
Since I didn't come up with a clever "grep" pattern to work across
line boundaries, I used pickaxe to find a block of "word 'work'
appears near the end of line, possibly followed by a run of
whitespaces or asterisks, then a newline, and then possibly a run of
whitespaces or asterisks, then word 'tree'" in the comparison
between an empty tree and what we have today, like so:
$ LF=$'\n' WS="[* "$'\t'"]"
$ git diff --pickaxe-regex -S"work$WS*$LF$WS*tree" \
4b825dc642cb6 -- ':(glob)Documentation/*.adoc' |
grep -A1 -e '^diff --git' -e "work${WS}$"
after finishing the previous two steps.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
Documentation/git-add.adoc | 2 +-
Documentation/git-read-tree.adoc | 2 +-
Documentation/git-rm.adoc | 4 ++--
Documentation/git-submodule.adoc | 2 +-
Documentation/gitcli.adoc | 2 +-
5 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
index 18e7ed9b79..ced77a4713 100644
--- a/Documentation/git-add.adoc
+++ b/Documentation/git-add.adoc
@@ -173,7 +173,7 @@ for `git add --no-all <pathspec>...`, i.e. ignored removed files.
`--ignore-missing`::
This option can only be used together with `--dry-run`. By using
this option the user can check if any of the given files would
- be ignored, no matter if they are already present in the work
+ be ignored, no matter if they are already present in the working
tree or not.
`--no-warn-embedded-repo`::
diff --git a/Documentation/git-read-tree.adoc b/Documentation/git-read-tree.adoc
index 9d60badd74..0110ac9cb8 100644
--- a/Documentation/git-read-tree.adoc
+++ b/Documentation/git-read-tree.adoc
@@ -43,7 +43,7 @@ OPTIONS
abort the operation.
-u::
- After a successful merge, update the files in the work
+ After a successful merge, update the files in the working
tree with the result of the merge.
-i::
diff --git a/Documentation/git-rm.adoc b/Documentation/git-rm.adoc
index a7a3068381..dce054ea5d 100644
--- a/Documentation/git-rm.adoc
+++ b/Documentation/git-rm.adoc
@@ -152,7 +152,7 @@ git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached
SUBMODULES
----------
Only submodules using a gitfile (which means they were cloned
-with a Git version 1.7.8 or newer) will be removed from the work
+with a Git version 1.7.8 or newer) will be removed from the working
tree, as their repository lives inside the `.git` directory of the
superproject. If a submodule (or one of those nested inside it)
still uses a `.git` directory, `git rm` moves the submodules
@@ -164,7 +164,7 @@ will be staged (unless `--cached` or `-n` are used).
A submodule is considered up to date when the `HEAD` is the same as
recorded in the index, no tracked files are modified and no untracked
files that aren't ignored are present in the submodule's working tree.
-Ignored files are deemed expendable and won't stop a submodule's work
+Ignored files are deemed expendable and won't stop a submodule's working
tree from being removed.
If you only want to remove the local checkout of a submodule from your
diff --git a/Documentation/git-submodule.adoc b/Documentation/git-submodule.adoc
index bdba17d166..df682b8b10 100644
--- a/Documentation/git-submodule.adoc
+++ b/Documentation/git-submodule.adoc
@@ -123,7 +123,7 @@ See the add subcommand for the definition of default remote.
deinit [-f|--force] (--all|[--] <path>...)::
Unregister the given submodules, i.e. remove the whole
- `submodule.$name` section from .git/config together with their work
+ `submodule.$name` section from .git/config together with their working
tree. Further calls to `git submodule update`, `git submodule foreach`
and `git submodule sync` will skip any unregistered submodules until
they are initialized again, so use this command if you don't want to
diff --git a/Documentation/gitcli.adoc b/Documentation/gitcli.adoc
index db88e84aaf..d3df9fed31 100644
--- a/Documentation/gitcli.adoc
+++ b/Documentation/gitcli.adoc
@@ -35,7 +35,7 @@ arguments. Here are the rules:
* When an argument can be misunderstood as either a revision or a path,
they can be disambiguated by placing `--` between them.
- E.g. `git diff -- HEAD` is, "I have a file called HEAD in my work
+ E.g. `git diff -- HEAD` is, "I have a file called HEAD in my working
tree. Please show changes between the version I staged in the index
and what I have in the working tree for that file", not "show the difference
between the HEAD commit and the working tree as a whole". You can say
--
2.52.0-rc1-455-g30608eb744
^ permalink raw reply related [flat|nested] 5+ messages in thread