[PATCH v5 4/4] Documentation: Describe 'submodule update --remote' use case

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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 <wking@xxxxxxxxxx>
---
 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 majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html




[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]