On Thu, Jan 16, 2014 at 12:21:04PM -0800, Junio C Hamano wrote [1]: > 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???".
There have been other interpretation issues with the --remote option as well. With this commit, I try to make it clear that there is no implicit floating going on; --remote lets you explicitly integrate the upstream branch in your current HEAD (just like running 'git pull' in the submodule). The only distinction with the current 'git pull' is the config location/setting used for the upstream branch, which is hopefully clear now. With syncing between the out-of-tree submodule config and the in-tree superproject .gitmodules [2], you wouldn't have to chose between (or manually sync) "easily distributable .gitmodules settings" and "native submodule pull", but this patch is my take on the current situation. [1]: http://article.gmane.org/gmane.comp.version-control.git/240529 [2]: http://article.gmane.org/gmane.comp.version-control.git/240336 Signed-off-by: W. Trevor King <wk...@tremily.us> --- Documentation/git-submodule.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2e1c7a2..21cb59a 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -299,6 +299,16 @@ In order to ensure a current tracking branch state, `update --remote` fetches the submodule's remote repository before calculating the SHA-1. If you don't want to fetch, you should use `submodule update --remote --no-fetch`. ++ +Use this option to integrate changes from the upstream subproject with +your submodule's current HEAD. Alternatively, you can run `git pull` +from the submodule, which is equivalent except for the remote branch +name: `update --remote` uses the default upstream repository and +`submodule.<name>.branch`, while `git pull` uses the submodule's +`branch.<name>.merge`. Prefer `submodule.<name>.branch` if you want +to distribute the default upstream branch with the superproject and +`branch.<name>.merge` if you want a more native feel while working in +the submodule itself. -N:: --no-fetch:: -- 1.8.5.2.8.g0f6c0d1 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
