path: root/Documentation/git-pull.txt
diff options
authorStefan Beller <>2017-06-23 19:13:02 (GMT)
committerJunio C Hamano <>2017-06-23 22:36:53 (GMT)
commita6d7eb2c7a6a402a938824bcf1c5f331dd1a06bb (patch)
treeaf56f09949eb1808fcd1d0afdac78e23b38c6230 /Documentation/git-pull.txt
parent8c69832d137042a4368248a995bebcc5b964a87b (diff)
pull: optionally rebase submodules (remote submodule changes only)
Teach pull to optionally update submodules when '--recurse-submodules' is provided. This will teach pull to run 'submodule update --rebase' when the '--recurse-submodules' and '--rebase' flags are given under specific circumstances. On a rebase workflow: ===================== 1. Both sides change the submodule ------------------------------ Let's assume the following history in a submodule: H---I---J---K---L local branch \ M---N---O---P remote branch and the following in the superproject (recorded submodule in parens): A(H)---B(I)---F(K)---G(L) local branch \ C(N)---D(N)---E(P) remote branch In an ideal world this would rebase the submodule and rewrite the submodule pointers that the superproject points at such that the superproject looks like A(H)---B(I) F(K')---G(L') rebased branch \ / C(N)---D(N)---E(P) remote branch and the submodule as: J---K---L (old dangeling tip) / H---I J'---K'---L' rebased branch \ / M---N---O---P remote branch And if a conflict arises in the submodule the superproject rebase would stop at that commit at which the submodule conflict occurs. Currently a "pull --rebase" in the superproject produces a merge conflict as the submodule pointer changes are conflicting and cannot be resolved. 2. Local submodule changes only ----------------------- Assuming histories as above, except that the remote branch would not contain submodule changes, then a result as A(H)---B(I) F(K)---G(L) rebased branch \ / C(I)---D(I)---E(I) remote branch is desire-able. This is what currently happens in rebase. If the recursive flag is given, the ideal git would produce a superproject as: A(H)---B(I) F(K')---G(L') rebased branch (incl. sub rebase!) \ / C(I)---D(I)---E(I) remote branch and the submodule as: J---K---L (old dangeling tip) / H---I J'---K'---L' locally rebased branch \ / M---N---O---P advanced branch This patch doesn't address this issue, however a test is added that this fails up front. 3. Remote submodule changes only ---------------------- Assuming histories as in (1) except that the local superproject branch would not have touched the submodule the rebase already works out in the superproject with no conflicts: A(H)---B(I) F(P)---G(P) rebased branch (no sub changes) \ / C(N)---D(N)---E(P) remote branch The recurse flag as presented in this patch would additionally update the submodule as: H---I J'---K'---L' rebased branch \ / M---N---O---P remote branch As neither J, K, L nor J', K', L' are referred to from the superproject, no rewriting of the superproject commits is required. Conclusion for 'pull --rebase --recursive' ----------------------------------------- If there are no local superproject changes it is sufficient to call "submodule update --rebase" as this produces the desired results. In case of conflicts, the behavior is the same as in 'submodule update --recursive' which is assumed to be sane. This patch implements (3) only. On a merge workflow: ==================== We'll start off with the same underlying DAG as in (1) in the rebase workflow. So in an ideal world a 'pull --merge --recursive' would produce this: H---I---J---K---L----X \ / M---N---O---P with X as the new merge-commit in the submodule and the superproject as: A(H)---B(I)---F(K)---G(L)---Y(X) \ / C(N)---D(N)---E(P) However modifying the submodules on the fly is not supported in git-merge such that Y(X) is not easy to produce in a single patch. In fact git-merge doesn't know about submodules at all. However when at least one side does not contain commits touching the submodule at all, then we do not need to perform the merge for the submodule but a fast-forward can be done via checking out either L or P in the submodule. This strategy is implemented in 68d03e4a6e (Implement automatic fast-forward merge for submodules, 2010-07-07) already, so to align with the rebase behavior we need to also update the worktree of the submodule. Signed-off-by: Brandon Williams <> Signed-off-by: Stefan Beller <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/git-pull.txt')
1 files changed, 6 insertions, 6 deletions
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index e414185..b201af6 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -86,12 +86,12 @@ OPTIONS
This option controls if new commits of all populated submodules should
- be fetched too (see linkgit:git-config[1] and linkgit:gitmodules[5]).
- That might be necessary to get the data needed for merging submodule
- commits, a feature Git learned in 1.7.3. Notice that the result of a
- merge will not be checked out in the submodule, "git submodule update"
- has to be called afterwards to bring the work tree up to date with the
- merge result.
+ be fetched and updated, too (see linkgit:git-config[1] and
+ linkgit:gitmodules[5]).
+If the checkout is done via rebase, local submodule commits are rebased as well.
+If the update is done via merge, the submodule conflicts are resolved and checked out.
Options related to merging