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

Re: [PATCH v4 6/6] Documentation: Describe 'submodule update' modes in detail

From
Junio C Hamano <gitster@pobox.com>
Date
Jan 16, 2014, 20:21 UTC
Message-ID
<xmqqeh47znin.fsf@gitster.dls.corp.google.com>
In-Reply-To
<4a8dca477ed5b190767d6a4619c593a83f86f082.1389837412.git.wking@tremily.us>
"W. Trevor King" <wking@tremily.us> writes:
Show 46 quoted lines
> The old documentation did not distinguish between cloning and
> non-cloning updates and lacked clarity on which operations would lead
> to detached HEADs, and which would not.  The new documentation
> addresses these issues while updating the docs to reflect the changes
> introduced by this branch's explicit local branch creation in
> module_clone.
>
> I also add '--checkout' to the usage summary and group the update-mode
> options into a single set.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
>  Documentation/git-submodule.txt | 36 +++++++++++++++++++++++++++---------
>  Documentation/gitmodules.txt    |  4 ++++
>  2 files changed, 31 insertions(+), 9 deletions(-)
>
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index bfef8a0..02500b4 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -15,8 +15,8 @@ SYNOPSIS
>  'git submodule' [--quiet] init [--] [<path>...]
>  'git submodule' [--quiet] deinit [-f|--force] [--] <path>...
>  'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]
> -	      [-f|--force] [--rebase] [--reference <repository>] [--depth <depth>]
> -	      [--merge] [--recursive] [--] [<path>...]
> +	      [-f|--force] [--rebase|--merge|--checkout] [--reference <repository>]
> +	      [--depth <depth>] [--recursive] [--] [<path>...]
>  'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
>  	      [commit] [--] [<path>...]
>  'git submodule' [--quiet] foreach [--recursive] <command>
> @@ -155,13 +155,31 @@ 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.
> +	checkout the commit specified in the index of the containing
> +	repository.  The update mode defaults to 'checkout', but be
> +	configured with the 'submodule.<name>.update' setting or the
> +	'--rebase', '--merge', or 'checkout' options.
Not '--checkout'?

Other than that, the updated text above is far easier to understand. Good job.

Show 6 quoted lines
> ++
> +For updates that clone missing submodules, checkout-mode updates will
> +create submodules with detached HEADs; all other modes will create
> +submodules with a local branch named after 'submodule.<path>.branch'.
> ++
> +For updates that do not clone missing submodules, the submodule's HEAD
That is, updates that update submodules that are already checked out?
Show 6 quoted lines
> +is only touched when the remote reference does not match the
> +submodule's HEAD (for none-mode updates, the submodule is never
> +touched).  The remote reference is usually the gitlinked commit from
> +the superproject's tree, but with '--remote' it is the upstream
> +subproject's 'submodule.<name>.branch'.  This remote reference is
> +integrated with the submodule's HEAD using the specified update mode.

I think copying some motivation from the log message of 06b1abb5 (submodule update: add --remote for submodule's upstream changes, 2012-12-19) would help the readers here. A naïve expectation from a casual reader of the above would be "The superproject's tree ought to point at the same commit as the tip of the branch used in the submodule (modulo mirroring delays and somesuch), if the repository of the superproject and submodules are maintained properly", which would lead to "when would any sane person need to use --remote in the first place???".

If I am reading 06b1abb5 correctly, the primary motivation behind "--remote" seems to be that it is exactly to help the person who wants to update superproject to satisify the "... are maintained properly" part by fetching the latest in each of the submodules in his superproject in preparation to 'git add .' them. I still do not think "--remote" was a better way than the "foreach", but that is a separate topic.

If the person who works in the superproject does not control the progress of, and/or does not care what development is happening in, the submodules, he can push the superproject tree out without even bothering to update the commits in the submodules bound to his superproject tree, and the consumers of such a superproject could catch up with the advancement of submodule by using --remote individually to bring themselves up to date. But I do not think that is what you envisioned as the best recommended practice when you wrote 06b1abb5.

Show 27 quoted lines
> +For checkout-mode updates, that will result in a detached HEAD.  For
> +rebase- and merge-mode updates, the commit referenced by the
> +submodule's HEAD may change, but the symbolic reference will remain
> +unchanged (i.e. checked-out branches will still be checked-out
> +branches, and detached HEADs will still be detached HEADs).  If none
> +of the builtin modes fit your needs, set 'submodule.<name>.update' to
> +'!command' to configure a custom integration command.  'command' can
> +be any arbitrary shell command that takes a single argument, namely
> +the sha1 to update to.
>  +
>  If the submodule is not yet initialized, and you just want to use the
>  setting as stored in .gitmodules, you can automatically initialize the
> diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
> index f7be93f..36e5447 100644
> --- a/Documentation/gitmodules.txt
> +++ b/Documentation/gitmodules.txt
> @@ -53,6 +53,10 @@ submodule.<name>.branch::
>  	A remote branch name for tracking updates in the upstream submodule.
>  	If the option is not specified, it defaults to 'master'.  See the
>  	`--remote` documentation in linkgit:git-submodule[1] for details.
> ++
> +This branch name is also used for the local branch created by
> +non-checkout cloning updates.  See the 'update' documentation in
> +linkgit:git-submodule[1] for details.
>  
>  submodule.<name>.fetchRecurseSubmodules::
>  	This option can be used to control recursive fetching of this

Other than the above minor nits, the updated text was very readable. Thanks.

Previous: W. Trevor KingNext: W. Trevor King
Message 71 of 102 in “Introduce git submodule add|update --attach”
  1. Introduce git submodule add|update --attachFrancesco Pretto, Dec 30, 2013
  2. Phil HordDec 31, 2013
  3. Francesco PrettoJan 2, 2014
  4. Junio C HamanoJan 13, 2014
  5. Junio C HamanoJan 2, 2014
  6. Francesco PrettoJan 2, 2014
  7. Francesco PrettoJan 3, 2014
  8. Francesco PrettoJan 3, 2014
  9. submodule: Respect reqested branch on all clonesW. Trevor King, Jan 3, 2014
  10. Heiko VoigtJan 4, 2014
  11. W. Trevor KingJan 4, 2014
  12. Heiko VoigtJan 5, 2014
  13. W. Trevor KingJan 5, 2014
  14. Francesco PrettoJan 5, 2014
  15. [RFC v2] submodule: Respect requested branch on all clonesW. Trevor King, Jan 5, 2014
  16. Heiko VoigtJan 5, 2014
  17. W. Trevor KingJan 5, 2014
  18. Heiko VoigtJan 5, 2014
  19. W. Trevor KingJan 5, 2014
  20. W. Trevor KingJan 6, 2014
  21. W. Trevor KingJan 6, 2014
  22. Heiko VoigtJan 6, 2014
  23. Francesco PrettoJan 6, 2014
  24. Francesco PrettoJan 6, 2014
  25. Junio C HamanoJan 7, 2014
  26. Francesco PrettoJan 7, 2014
  27. W. Trevor KingJan 7, 2014
  28. Francesco PrettoJan 7, 2014
  29. Heiko VoigtJan 7, 2014
  30. Francesco PrettoJan 8, 2014
  31. W. Trevor KingJan 8, 2014
  32. Francesco PrettoJan 8, 2014
  33. Francesco PrettoJan 8, 2014
  34. W. Trevor KingJan 9, 2014
  35. Francesco PrettoJan 9, 2014
  36. W. Trevor KingJan 9, 2014
  37. Jens LehmannJan 9, 2014
  38. W. Trevor KingJan 9, 2014
  39. Jens LehmannJan 9, 2014
  40. W. Trevor KingJan 9, 2014
  41. Jens LehmannJan 9, 2014
  42. W. Trevor KingJan 9, 2014
  43. Heiko VoigtJan 14, 2014
  44. W. Trevor KingJan 14, 2014
  45. Heiko VoigtJan 14, 2014
  46. W. Trevor KingJan 14, 2014
  47. Heiko VoigtJan 14, 2014
  48. W. Trevor KingJan 14, 2014
  49. Heiko VoigtJan 14, 2014
  50. W. Trevor KingJan 14, 2014
  51. Heiko VoigtJan 14, 2014
  52. Francesco PrettoJan 15, 2014
  53. 0/6 submodule: Local branch creation in module_cloneW. Trevor King, Jan 16, 2014
  54. 1/6 submodule: Make 'checkout' update_module explicitW. Trevor King, Jan 16, 2014
  55. Junio C HamanoJan 16, 2014
  56. W. Trevor KingJan 16, 2014
  57. Francesco PrettoJan 16, 2014
  58. W. Trevor KingJan 16, 2014
  59. 2/6 submodule: Document module_clone arguments in commentsW. Trevor King, Jan 16, 2014
  60. 3/6 submodule: Explicit local branch creation in module_cloneW. Trevor King, Jan 16, 2014
  61. Junio C HamanoJan 16, 2014
  62. W. Trevor KingJan 16, 2014
  63. Junio C HamanoJan 16, 2014
  64. W. Trevor KingJan 16, 2014
  65. 4/6 t7406: Just-cloned checkouts update to the gitlinked hash with 'reset'W. Trevor King, Jan 16, 2014
  66. Junio C HamanoJan 16, 2014
  67. W. Trevor KingJan 16, 2014
  68. Junio C HamanoJan 16, 2014
  69. 5/6 t7406: Add explicit tests for head attachement after cloning updatesW. Trevor King, Jan 16, 2014
  70. 6/6 Documentation: Describe 'submodule update' modes in detailW. Trevor King, Jan 16, 2014
  71. Junio C HamanoJan 16, 2014
  72. W. Trevor KingJan 16, 2014
  73. John KeepingJan 16, 2014
  74. W. Trevor KingJan 16, 2014
  75. Junio C HamanoJan 16, 2014
  76. W. Trevor KingJan 17, 2014
  77. 0/4 submodule: Local branch creation in module_cloneW. Trevor King, Jan 26, 2014
  78. 1/4 submodule: Make 'checkout' update_module explicitW. Trevor King, Jan 26, 2014
  79. Eric SunshineJan 27, 2014
  80. W. Trevor KingJan 27, 2014
  81. 2/4 submodule: Document module_clone arguments in commentsW. Trevor King, Jan 26, 2014
  82. 3/4 submodule: Explicit local branch creation in module_cloneW. Trevor King, Jan 26, 2014
  83. 4/4 Documentation: Describe 'submodule update --remote' use caseW. Trevor King, Jan 26, 2014
  84. Philip OakleyJan 16, 2014
  85. W. Trevor KingJan 16, 2014
  86. Francesco PrettoJan 8, 2014
  87. W. Trevor KingJan 9, 2014
  88. Francesco PrettoJan 7, 2014
  89. Heiko VoigtJan 6, 2014
  90. W. Trevor KingJan 6, 2014
  91. Francesco PrettoJan 5, 2014
  92. W. Trevor KingJan 5, 2014
  93. W. Trevor KingJan 5, 2014
  94. Heiko VoigtJan 6, 2014
  95. Junio C HamanoJan 6, 2014
  96. W. Trevor KingJan 6, 2014
  97. Junio C HamanoJan 6, 2014
  98. Francesco PrettoJan 7, 2014
  99. Junio C HamanoJan 7, 2014
  100. W. Trevor KingJan 7, 2014
  101. Junio C HamanoJan 7, 2014
  102. W. Trevor KingJan 7, 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.