branch: add --recurse-submodules option for branch creation
commit961b130d20c9aea322b94a639a63ec8cca9f14fc
authorGlen Choo <chooglen@google.com>
Sat, 29 Jan 2022 00:04:45 +0000 (28 16:04 -0800)
committerJunio C Hamano <gitster@pobox.com>
Fri, 4 Feb 2022 16:16:39 +0000 (4 08:16 -0800)
treee839045c22b34f90babe307ddf734c3be4f0a16d
parent6e0a2ca0277e6010cd403c70d8f15b66af345d33
branch: add --recurse-submodules option for branch creation

To improve the submodules UX, we would like to teach Git to handle
branches in submodules. Start this process by teaching "git branch" the
--recurse-submodules option so that "git branch --recurse-submodules
topic" will create the `topic` branch in the superproject and its
submodules.

Although this commit does not introduce breaking changes, it does not
work well with existing --recurse-submodules commands because "git
branch --recurse-submodules" writes to the submodule ref store, but most
commands only consider the superproject gitlink and ignore the submodule
ref store. For example, "git checkout --recurse-submodules" will check
out the commits in the superproject gitlinks (and put the submodules in
detached HEAD) instead of checking out the submodule branches.

Because of this, this commit introduces a new configuration value,
`submodule.propagateBranches`. The plan is for Git commands to
prioritize submodule ref store information over superproject gitlinks if
this value is true. Because "git branch --recurse-submodules" writes to
submodule ref stores, for the sake of clarity, it will not function
unless this configuration value is set.

This commit also includes changes that support working with submodules
from a superproject commit because "branch --recurse-submodules" (and
future commands) need to read .gitmodules and gitlinks from the
superproject commit, but submodules are typically read from the
filesystem's .gitmodules and the index's gitlinks. These changes are:

* add a submodules_of_tree() helper that gives the relevant
  information of an in-tree submodule (e.g. path and oid) and
  initializes the repository
* add is_tree_submodule_active() by adding a treeish_name parameter to
  is_submodule_active()
* add the "submoduleNotUpdated" advice to advise users to update the
  submodules in their trees

Incidentally, fix an incorrect usage string that combined the 'list'
usage of git branch (-l) with the 'create' usage; this string has been
incorrect since its inception, a8dfd5eac4 (Make builtin-branch.c use
parse_options., 2007-10-07).

Helped-by: Jonathan Tan <jonathantanmy@google.com>
Signed-off-by: Glen Choo <chooglen@google.com>
Reviewed-by: Jonathan Tan <jonathantanmy@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
14 files changed:
Documentation/config/advice.txt
Documentation/config/submodule.txt
Documentation/git-branch.txt
advice.c
advice.h
branch.c
branch.h
builtin/branch.c
builtin/submodule--helper.c
submodule-config.c
submodule-config.h
submodule.c
submodule.h
t/t3207-branch-submodule.sh [new file with mode: 0755]