Differences

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

--- git_subtree [2017/11/07 02:17] – [Example] rpjday
+++ git_subtree [2018/02/13 17:05] (current) – [Links] rpjday
@@ Line 1: / Line 1: @@
 ==== Overview ====
-The good and the bad of ''git subtree''.
+The good and the bad of ''git subtree'' (mostly the good).
 ==== Links ====
+  * [[https://medium.com/@v/git-subtrees-a-tutorial-6ff568381844|git subtrees: a tutorial (2014)]]
   * [[https://www.atlassian.com/blog/git/alternatives-to-git-submodule-git-subtree|Atlassian --
-Git subtree: the alternative to Git submodule]]
+Git subtree: the alternative to Git submodule (2013)]]
+  * [[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]]
+  * [[https://makingsoftware.wordpress.com/2013/02/16/using-git-subtrees-for-repository-separation/|Using Git subtrees for repository separation (2013)]]
+  * [[https://lostechies.com/johnteague/2014/04/04/using-git-subtrees-to-split-a-repository/|Using Git subtrees to split a repository (2014)]]
 ==== Synopsis ====
@@ Line 21: / Line 29: @@
        git subtree merge -P <prefix> <commit>
        git subtree split -P <prefix> [OPTIONS] [<commit>]
+       ... 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
+       -q, --quiet
+           Suppress unnecessary output messages on stderr.
+       -d, --debug
+           Produce even more unnecessary output messages on stderr.
+       -P <prefix>, --prefix=<prefix>
+           Specify the path in the repository to the subtree you want to manipulate. This option
+           is mandatory for all commands.
+       -m <message>, --message=<message>
+           This option is only valid for add, merge and pull (unsure). Specify <message> as the
+           commit message for the merge commit.
 </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 32: / Line 90: @@
 === Start a subtree, and examine it ===
+The synopsis:
+<code>
+$ git subtree add -P <prefix> <repository> <ref>
+</code>
+The example:
 <code>
@@ Line 75: / Line 141: @@
 </code>
-=== To manually update subtree ===
+==== To manually update subtree ====
+Synopsis:
+<code>
+$ git subtree pull -P <prefix> <repository> <ref>
+</code>
+Example:
 <code>
@@ Line 81: / 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>