Re: [PATCH] doc: remove mentions of .gitmodules !command syntax

From: Petar Vutov <pvutov@imap.cc>
Date: Jul 12, 2023, 18:48 UTC
Message-ID: <7090349c-4485-d5c4-1f26-190974864f72@imap.cc>
In-Reply-To: <xmqqfs5tt3qz.fsf@gitster.g>

On 7/12/23 19:54, Junio C Hamano wrote:

Show 9 quoted lines

> 
> Perhaps
> 
>      "... available via the ... configuration variable, and cannot be
>      used in the .gitmodules file"
> 
> would have helped you?
> 
> Thanks.

I think that addition is good and makes the intent clearer.

But it's slightly wrong - only 'custom command' cannot be used in .gitmodules. 'none' is legal (and mentioned in the gitmodules doc as such).

What about something like this?

 From 7b2fcd9a56b4954863cc74e1cf89a4b9d9d3ad52 Mon Sep 17 00:00:00 2001
From: Petar Vutov <pvutov@imap.cc>
Date: Wed, 12 Jul 2023 20:40:10 +0200
Subject: [PATCH] docs: highlight that .gitmodules does not support !command

The `custom command` and `none` entries are described as sharing the same limitations, but one is allowed in .gitmodules and the other is not. Instead, describe their limitations separately and with slightly more detail.

Signed-off-by: Petar Vutov <pvutov@imap.cc>
---
  Documentation/git-submodule.txt | 9 ++++++---
  1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-submodule.txt 
b/Documentation/git-submodule.txt
index 4d3ab6b9f9..eb024a1531 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -160,16 +160,19 @@ checked out in the submodule.
  	merge;; the commit recorded in the superproject will be merged
  	    into the current branch in the submodule.

-The following 'update' procedures are only available via the
-`submodule.<name>.update` configuration variable:
-
  	custom command;; arbitrary shell command that takes a single
  	    argument (the sha1 of the commit recorded in the
  	    superproject) is executed. When `submodule.<name>.update`
  	    is set to '!command', the remainder after the exclamation mark
  	    is the custom command.
++
+Custom commands are only available via the `submodule.<name>.update`
+configuration variable. They cannot be used in the .gitmodules file.

  	none;; the submodule is not updated.
++
+The `none` update procedure is only available via the .gitmodules file
+or the `submodule.<name>.update` configuration variable.

  If the submodule is not yet initialized, and you just want to use the
  setting as stored in `.gitmodules`, you can automatically initialize the

-- 
2.41.0