git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v2 08/11] worktree: use 'worktree' over 'working tree'

From
Derrick Stolee via GitGitGadget <gitgitgadget@gmail.com>
Date
Feb 22, 2022, 00:17 UTC
Message-ID
<65a0cd527118578c98a6862460caa86ecb49735a.1645489080.git.gitgitgadget@gmail.com>
In-Reply-To
<pull.1154.v2.git.1645489080.gitgitgadget@gmail.com>
From: Derrick Stolee <derrickstolee@github.com>

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 fourth of multiple changes to git-worktree.txt, restricted to the REFS section.

This section previously described "per working tree" refs but they are now replaced with "per-worktree" refs, which matches the definition in glossary-content.txt.

The first paragraph of this section was also a bit confusing, so it is cleaned up to make it easier to understand.

Helped-by: Taylor Blau <m3@ttaylorr.com>
Signed-off-by: Derrick Stolee <derrickstolee@github.com>
---
 Documentation/git-worktree.txt | 31 +++++++++++++++----------------
 1 file changed, 15 insertions(+), 16 deletions(-)
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 358325ac073..41c6d503937 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -256,24 +256,23 @@ have two worktrees, at `/abc/def/ghi` and `/abc/def/ggg`, then `ghi` or
 
 REFS
 ----
-In multiple working trees, some refs may be shared between all working
-trees and some refs are local. One example is `HEAD` which is different for each
-working tree. This section is about the sharing rules and how to access
-refs of one working tree from another.
-
-In general, all pseudo refs are per working tree and all refs starting
-with `refs/` are shared. Pseudo refs are ones like `HEAD` which are
-directly under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are
-exceptions, however: refs inside `refs/bisect` and `refs/worktree` are not
-shared.
-
-Refs that are per working tree can still be accessed from another
-working tree via two special paths, `main-worktree` and `worktrees`. The
-former gives access to per-working tree refs of the main working tree,
-while the latter to all linked working trees.
+When using multiple worktrees, some refs are shared between all worktrees,
+but others are specific to an individual worktree. One example is `HEAD`,
+which is different for each worktree. This section is about the sharing
+rules and how to access refs of one worktree from another.
+
+In general, all pseudo refs are per-worktree and all refs starting with
+`refs/` are shared. Pseudo refs are ones like `HEAD` which are directly
+under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are exceptions,
+however: refs inside `refs/bisect` and `refs/worktree` are not shared.
+
+Refs that are per-worktree can still be accessed from another worktree via
+two special paths, `main-worktree` and `worktrees`. The former gives
+access to per-worktree refs of the main worktree, while the latter to all
+linked worktrees.
 
 For example, `main-worktree/HEAD` or `main-worktree/refs/bisect/good`
-resolve to the same value as the main working tree's `HEAD` and
+resolve to the same value as the main worktree's `HEAD` and
 `refs/bisect/good` respectively. Similarly, `worktrees/foo/HEAD` or
 `worktrees/bar/refs/bisect/bad` are the same as
 `$GIT_COMMON_DIR/worktrees/foo/HEAD` and
-- 
gitgitgadget
Previous: Derrick Stolee via GitGitGadgetNext: Taylor Blau
Message 41 of 63 in “Updates to worktree code and docs”
  1. 00/11 Updates to worktree code and docsDerrick Stolee via GitGitGadget, Feb 20, 2022
  2. 01/11 worktree: combine two translatable messagesDerrick Stolee via GitGitGadget, Feb 20, 2022
  3. Junio C HamanoFeb 20, 2022
  4. Derrick StoleeFeb 20, 2022
  5. 03/11 worktree: extract copy_sparse_checkout()Derrick Stolee via GitGitGadget, Feb 20, 2022
  6. 02/11 worktree: extract copy_filtered_worktree_config()Derrick Stolee via GitGitGadget, Feb 20, 2022
  7. Junio C HamanoFeb 20, 2022
  8. 04/11 worktree: extract checkout_worktree()Derrick Stolee via GitGitGadget, Feb 20, 2022
  9. Taylor BlauFeb 20, 2022
  10. 05/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 20, 2022
  11. Junio C HamanoFeb 20, 2022
  12. Derrick StoleeFeb 20, 2022
  13. Philip OakleyFeb 24, 2022
  14. Derrick StoleeFeb 24, 2022
  15. Philip OakleyMar 3, 2022
  16. 07/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 20, 2022
  17. 06/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 20, 2022
  18. 08/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 20, 2022
  19. Taylor BlauFeb 20, 2022
  20. 09/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 20, 2022
  21. Taylor BlauFeb 20, 2022
  22. Derrick StoleeFeb 21, 2022
  23. 10/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 20, 2022
  24. 11/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 20, 2022
  25. Taylor BlauFeb 20, 2022
  26. Derrick StoleeFeb 21, 2022
  27. Taylor BlauFeb 20, 2022
  28. Taylor BlauFeb 20, 2022
  29. 00/11 Updates to worktree code and docsDerrick Stolee via GitGitGadget, Feb 22, 2022
  30. 01/11 worktree: combine two translatable messagesDerrick Stolee via GitGitGadget, Feb 22, 2022
  31. 02/11 worktree: extract copy_filtered_worktree_config()Derrick Stolee via GitGitGadget, Feb 22, 2022
  32. 04/11 worktree: extract checkout_worktree()Derrick Stolee via GitGitGadget, Feb 22, 2022
  33. 05/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 22, 2022
  34. Junio C HamanoFeb 22, 2022
  35. Elijah NewrenFeb 23, 2022
  36. 03/11 worktree: extract copy_sparse_checkout()Derrick Stolee via GitGitGadget, Feb 22, 2022
  37. 06/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 22, 2022
  38. Junio C HamanoFeb 22, 2022
  39. Derrick StoleeFeb 22, 2022
  40. 07/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 22, 2022
  41. 08/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 22, 2022
  42. Taylor BlauFeb 22, 2022
  43. Derrick StoleeFeb 22, 2022
  44. Taylor BlauFeb 23, 2022
  45. 09/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 22, 2022
  46. 11/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 22, 2022
  47. 10/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 22, 2022
  48. Taylor BlauFeb 22, 2022
  49. Junio C HamanoFeb 23, 2022
  50. Elijah NewrenFeb 23, 2022
  51. Derrick StoleeFeb 23, 2022
  52. 00/11 Updates to worktree code and docsDerrick Stolee via GitGitGadget, Feb 23, 2022
  53. 01/11 worktree: combine two translatable messagesDerrick Stolee via GitGitGadget, Feb 23, 2022
  54. 02/11 worktree: extract copy_filtered_worktree_config()Derrick Stolee via GitGitGadget, Feb 23, 2022
  55. 05/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 23, 2022
  56. 04/11 worktree: extract checkout_worktree()Derrick Stolee via GitGitGadget, Feb 23, 2022
  57. 03/11 worktree: extract copy_sparse_checkout()Derrick Stolee via GitGitGadget, Feb 23, 2022
  58. 06/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 23, 2022
  59. 08/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 23, 2022
  60. 07/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 23, 2022
  61. 09/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 23, 2022
  62. 10/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 23, 2022
  63. 11/11 worktree: use 'worktree' over 'working tree'Derrick Stolee via GitGitGadget, Feb 23, 2022

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.