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

[Derrick Stolee <stolee@gmail.com>]

On 1/27/2022 1:43 AM, Elijah Newren wrote:
> On Tue, Jan 25, 2022 at 10:42 AM Derrick Stolee via GitGitGadget
> <gitgitgadget@gmail.com> wrote:

>>  --worktree::
>> -       Similar to `--local` except that `.git/config.worktree` is
>> +       Similar to `--local` except that `$GIT_DIR/config.worktree` is
>>         read from or written to if `extensions.worktreeConfig` is
>> -       present. If not it's the same as `--local`.
>> +       enabled. If not it's the same as `--local`. Note that `$GIT_DIR`
>> +       is equal to `$GIT_COMMON_DIR` for the main worktree, but is of the
>> +       form `.git/worktrees/<worktree-name>/` for other worktrees. See
> 
> is of the form `$GIT_DIR/worktrees/<worktree-name>/`; .git isn't even
> a directory in other worktrees.

Thanks. I tried to catch all of these, but I missed one.
 
>> +       linkgit:git-worktree[1] to learn how to enable
>> +       `extensions.worktreeConfig`.
>>
>>  -f <config-file>::
>>  --file <config-file>::
>> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
>> index 9e862fbcf79..ea0ee9f8bb5 100644
>> --- a/Documentation/git-worktree.txt
>> +++ b/Documentation/git-worktree.txt
>> @@ -286,8 +286,8 @@ CONFIGURATION FILE
>>  ------------------
>>  By default, the repository `config` file is shared across all working
>>  trees. If the config variables `core.bare` or `core.worktree` are
>> -already present in the config file, they will be applied to the main
>> -working trees only.
>> +present in the common config file and `extensions.worktreeConfig` is
>> +disabled, then they will be applied to the main working trees only.
> 
> "main working trees"?  Is that an accidental plural?

Yes. Thanks.

>>  In order to have configuration specific to working trees, you can turn
>>  on the `worktreeConfig` extension, e.g.:
>> @@ -307,11 +307,16 @@ them to the `config.worktree` of the main working tree. You may also
>>  take this opportunity to review and move other configuration that you
>>  do not want to share to all working trees:
>>
>> - - `core.worktree` and `core.bare` should never be shared
>> + - `core.worktree` should never be shared.
>> +
>> + - `core.bare` should not be shared unless the value is `core.bare=false`.
> 
> The double negative makes for harder parsing.  Perhaps
>     - `core.bare` should not be shared if the value is `core.bare=true`
> ?

That is cleaner. Excellent.

>>   - `core.sparseCheckout` is recommended per working tree, unless you
>>     are sure you always use sparse checkout for all working trees.
>>
>> +See the documentation of `extensions.worktreeConfig` in
>> +linkgit:git-config[1] for more details.
>> +
>>  DETAILS
>>  -------
>>  Each linked working tree has a private sub-directory in the repository's
>> --
>> gitgitgadget
> 
> Thanks for documenting these details; I had some very minor comments
> but this is well written and very helpful.

Thanks for your recommended improvements.
-Stolee