Differences

This shows you the differences between two versions of the page.

--- git_subtree [2017/11/07 02:35] – [Links] rpjday
+++ git_subtree [2018/02/13 17:05] (current) – [Links] rpjday
@@ Line 8: / Line 8: @@
   * [[https://www.atlassian.com/blog/git/alternatives-to-git-submodule-git-subtree|Atlassian --
 Git subtree: the alternative to Git submodule (2013)]]
-  * [[https://developer.atlassian.com/blog/2015/05/the-power-of-git-subtree/|The power of Git subtree (2015)]]
+  * [[https://hpc.uni.lu/blog/2014/understanding-git-subtree/|Understanding Git subtree (2014)]]
+  * [[https://developer.atlassian.com/blog/2015/05/the-power-of-git-subtree/|Atlassian -- The power of Git subtree (2015)]]
   * [[https://medium.com/@porteneuve/mastering-git-subtrees-943d29a798ec|Mastering Git subtrees (2016)]]
   * [[https://gist.github.com/kvnsmth/4688345|A real world usage for Git subtrees]]
@@ Line 30: / Line 31: @@
        ... snip ...
+DESCRIPTION
+       Subtrees allow subprojects to be included within a subdirectory of the main project,
+       optionally including the subproject’s entire history.
+       For example, you could include the source code for a library as a subdirectory of your
+       application.
+       Subtrees are not to be confused with submodules, which are meant for the same task. Unlike
+       submodules, subtrees do not need any special constructions (like .gitmodule files or
+       gitlinks) be present in your repository, and do not force end-users of your repository to
+       do anything special or to understand how subtrees work. A subtree is just a subdirectory
+       that can be committed to, branched, and merged along with your project in any way you want.
+       ... snip...
 OPTIONS
@@ Line 47: / Line 63: @@
 </code>
-==== Example ====
+==== The good and the bad ====
+The good:
+  * Management of a simple workflow is easy.
+  * Older version of Git are supported (even older than v1.5.2).
+  * The sub-project’s code is available right after the clone of the super project is done.
+  * ''git subtree'' does not require users of your repository to learn anything new. They can ignore the fact that you are using git subtree to manage dependencies.
+  * ''git subtree'' does not add new metadata files like git submodule does (i.e., .gitmodule).
+  * Contents of the module can be modified without having a separate repository copy of the dependency somewhere else.
+The bad:
+  * You must learn about a new merge strategy (i.e. git subtree).
+  * Contributing code back upstream for the sub-projects is slightly more complicated.
+  * The responsibility of not mixing super and sub-project code in commits lies with you
+==== Setting up a subtree ====
 === Start a new branch ===
@@ Line 56: / Line 90: @@
 === Start a subtree, and examine it ===
+The synopsis:
+<code>
+$ git subtree add -P <prefix> <repository> <ref>
+</code>
+The example:
 <code>
@@ Line 99: / Line 141: @@
 </code>
-=== To manually update subtree ===
+==== To manually update subtree ====
+Synopsis:
+<code>
+$ git subtree pull -P <prefix> <repository> <ref>
+</code>
+Example:
 <code>
@@ Line 105: / Line 155: @@
   --prefix .vim/bundle/tpope-vim-surround \
   https://bitbucket.org/vim-plugins-mirror/vim-surround.git \
+  master \
+  --squash
+$
+</code>
+==== Add the subproject as a remote ====
+Add a remote (''-f'' means fetch immediately):
+<code>
+$ git remote add \
+  -f \
+  tpope-vim-surround \
+  https://bitbucket.org/vim-plugins-mirror/vim-surround.git
+$
+</code>
+Add the subtree:
+<code>
+$ git subtree add \
+  --prefix .vim/bundle/tpope-vim-surround \
+  tpope-vim-surround \
+  master \
+  --squash
+$
+</code>
+To update at a later date:
+<code>
+$ git fetch tpope-vim-surround master
+$ git subtree pull \
+  --prefix .vim/bundle/tpope-vim-surround \
+  tpope-vim-surround \
   master \
   --squash
 $
 </code>