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

[PATCH v2] submodule: Fix documentation of update subcommand

From
Michal Sojka <sojkam1@fel.cvut.cz>
Date
Feb 18, 2015, 22:48 UTC
Message-ID
<1424299716-21138-1-git-send-email-sojkam1@fel.cvut.cz>
In-Reply-To
<xmqqvbj0yx6c.fsf@gitster.dls.corp.google.com>
The documentation of 'git submodule update' has several problems:
1) It says that submodule.$name.update can be overridden by --checkout
   only if its value is `none`. This is not true, because both
   implementation and documentation of --checkout specifies that the
   override applies to all possible values.
2) The documentation of submodule.$name.update key is scattered across
   three places, which is confusing.
3) The documentation of submodule.$name.update in gitmodules.txt is
   incorrect, because the code always uses the value from .git/config
   and never from .gitmodules.

This patch fixes all three problems. Now, submodule.$name.update is fully documented in config.txt and the other files just refer to it. This is based on discussion between myself, Junio C Hamano and Jens Lehmann.

Signed-off-by: Michal Sojka <sojkam1@fel.cvut.cz>
---
 Documentation/config.txt        | 27 ++++++++++++++++++++++-----
 Documentation/git-submodule.txt | 17 ++++++++---------
 Documentation/gitmodules.txt    | 18 ++++++------------
 3 files changed, 36 insertions(+), 26 deletions(-)
diff --git a/Documentation/config.txt b/Documentation/config.txt
index ae6791d..f30cbbc 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -2411,12 +2411,29 @@ status.submodulesummary::
 
 submodule.<name>.path::
 submodule.<name>.url::
+	The path within this project and URL for a submodule. These
+	variables are initially populated by 'git submodule init';
+	edit them to override the URL and other values found in the
+	`.gitmodules` file. See linkgit:git-submodule[1] and
+	linkgit:gitmodules[5] for details.
+
 submodule.<name>.update::
-	The path within this project, URL, and the updating strategy
-	for a submodule.  These variables are initially populated
-	by 'git submodule init'; edit them to override the
-	URL and other values found in the `.gitmodules` file.  See
-	linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.
+	The default updating strategy for a submodule, used by `git
+	submodule update`. This variable is populated by `git
+	submodule init` from linkgit:gitmodules[5].
+
+	If the value is 'checkout' (the default), the new commit
+	specified in the superproject will be checked out in the
+	submodule on a detached HEAD.
+	If 'rebase', the current branch of the submodule will be
+	rebased onto the commit specified in the superproject.
+	If 'merge', the commit specified in the superproject will be
+	merged into the current branch in the submodule. If 'none',
+	the submodule with name `$name` will not be updated by
+	default.
+	If the value is of form '!command', it will cause `command` to
+	be run. `command` can be any arbitrary shell command that
+	takes a single argument, namely the sha1 to update to.
 
 submodule.<name>.branch::
 	The remote branch name for a submodule, used by `git submodule
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 8e6af65..c92908e 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -154,14 +154,13 @@ If `--force` is specified, the submodule's work tree will be removed even if
 it contains local modifications.
 
 update::
-	Update the registered submodules, i.e. clone missing submodules and
-	checkout the commit specified in the index of the containing repository.
-	This will make the submodules HEAD be detached unless `--rebase` or
-	`--merge` is specified or the key `submodule.$name.update` is set to
-	`rebase`, `merge` or `none`. `none` can be overridden by specifying
-	`--checkout`. Setting the key `submodule.$name.update` to `!command`
-	will cause `command` to be run. `command` can be any arbitrary shell
-	command that takes a single argument, namely the sha1 to update to.
+	Update the registered submodules to match what the superproject
+	expects by cloning missing submodules and updating the working
+	tree of the submodules. The "updating" can take various forms
+	and can be configured in .git/config by the
+	`submodule.$name.update` key or by explicitely giving one of
+	'--checkout' (the default), '--merge' or '--rebase' options. See
+	linkgit:git-config[1] for details.
 +
 If the submodule is not yet initialized, and you just want to use the
 setting as stored in .gitmodules, you can automatically initialize the
@@ -302,7 +301,7 @@ the submodule itself.
 	Checkout the commit recorded in the superproject on a detached HEAD
 	in the submodule. This is the default behavior, the main use of
 	this option is to override `submodule.$name.update` when set to
-	`merge`, `rebase` or `none`.
+	other value than `checkout`.
 	If the key `submodule.$name.update` is either not explicitly set or
 	set to `checkout`, this option is implicit.
 
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
index f6c0dfd..59efbfe 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -38,18 +38,12 @@ submodule.<name>.url::
 In addition, there are a number of optional keys:
 
 submodule.<name>.update::
-	Defines what to do when the submodule is updated by the superproject.
-	If 'checkout' (the default), the new commit specified in the
-	superproject will be checked out in the submodule on a detached HEAD.
-	If 'rebase', the current branch of the submodule will be rebased onto
-	the commit specified in the superproject. If 'merge', the commit
-	specified in the superproject will be merged into the current branch
-	in the submodule.
-	If 'none', the submodule with name `$name` will not be updated
-	by default.
-
-	This config option is overridden if 'git submodule update' is given
-	the '--merge', '--rebase' or '--checkout' options.
+	Defines what to do when the submodule is updated by the
+	superproject. This is only used by `git submodule init` to
+	initialize the variable of the same name in .git/config.
+	Allowed values here are 'checkout', 'rebase', 'merge' or
+	'none'. See linkgit:git-config[1] for their meaning and other
+	values that can be configured manually by users.
 
 submodule.<name>.branch::
 	A remote branch name for tracking updates in the upstream submodule.

-- 
2.1.4
Previous: Junio C HamanoNext: Junio C Hamano
Message 12 of 25 in “submodule: Fix documentation of update subcommand”
  1. submodule: Fix documentation of update subcommandMichal Sojka, Nov 3, 2014
  2. Junio C HamanoNov 3, 2014
  3. Jens LehmannNov 3, 2014
  4. Junio C HamanoNov 3, 2014
  5. Michal SojkaNov 3, 2014
  6. Junio C HamanoNov 3, 2014
  7. Jens LehmannNov 4, 2014
  8. Junio C HamanoNov 4, 2014
  9. Junio C HamanoNov 3, 2014
  10. Jens LehmannNov 3, 2014
  11. Junio C HamanoFeb 17, 2015
  12. submodule: Fix documentation of update subcommandMichal Sojka, Feb 18, 2015
  13. Junio C HamanoFeb 18, 2015
  14. Michal SojkaFeb 19, 2015
  15. submodule: Improve documentation of update subcommandMichal Sojka, Feb 19, 2015
  16. Junio C HamanoFeb 20, 2015
  17. Michal SojkaFeb 23, 2015
  18. submodule: Improve documentation of update subcommandMichal Sojka, Feb 23, 2015
  19. Junio C HamanoFeb 23, 2015
  20. Junio C HamanoFeb 23, 2015
  21. Michal SojkaMar 2, 2015
  22. submodule: Improve documentation of update subcommandMichal Sojka, Mar 2, 2015
  23. submodule: Improve documentation of update subcommandMichal Sojka, Mar 2, 2015
  24. Junio C HamanoMar 2, 2015
  25. Michal SojkaNov 3, 2014

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.