Re: [PATCH v5 1/5] Documentation: add extensions.worktreeConfig details

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Feb 6, 2022, 09:17 UTC
Message-ID: <CAPig+cS-3CxxyPGcy_vkeN_WYTRo1b-ZhJNdPy8ARZSNKkF1Xg@mail.gmail.com>
In-Reply-To: <1bd5f26271c9b1cff6c920bb91738ae903dccc61.1643641259.git.gitgitgadget@gmail.com>

On Mon, Jan 31, 2022 at 10:01 AM Derrick Stolee via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 6 quoted lines

> [...]
> Expand the documentation to help users discover the complexities of
> extensions.worktreeConfig by adding details and cross links in these
> locations (relative to Documentation/):
> [...]
> Signed-off-by: Derrick Stolee <dstolee@microsoft.com>

A few minor comments, which can be addressed later or not at all, and likely are not worth holding up the series...

Show 11 quoted lines

> diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt
> @@ -6,3 +6,34 @@ extensions.objectFormat::
> +extensions.worktreeConfig::
> +       If enabled, then worktrees will load config settings from the
> +       `$GIT_DIR/config.worktree` file in addition to the
> +       `$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and
> +       `$GIT_DIR` are the same for the main worktree, while other
> +       worktrees have `$GIT_DIR` equal to
> +       `$GIT_COMMON_DIR/worktrees/<worktree-name>/`. The settings in the
> +       `config.worktree` file will override settings from any other
> +       config files.

There have been some efforts[1][2] in the past to settle upon the term "working tree" instead of "worktree" when talking about worktrees in prose. (The term "worktree" is perfectly fine in paths, such as `.git/worktrees/`, and in the command name `git worktree`, of course.)

Documentation/git-worktree.txt calls it "<id>" rather than "<worktree-name>" since it is a unique identifier for the worktree which may or may not match the worktree's basename.

Documentation/git-worktree.txt talks simply about the path `.git/worktrees/` under the assumption that people will understand that `.git/` is the repository's common directory (which may not even be named `.git/` for a bare repository). Although saying $GIT_COMMON_DIR is certainly technically accurate, the simpler `.git/` doesn't seem to have caused any consternation. (Not a big deal. I mention it only to highlight the inconsistency between the existing and new documentation added here.)

The same comments apply to the rest of the patch.

[1]: bc483285b7 (Documentation/git-worktree: consistently use term "linked working tree", 2015-07-20) [2]: 4f375b2678 (git-worktree.txt: consistently use term "working tree", 2020-08-03)