Docs: Re-integrate an already extracted subtree that still exists in the source

README.md

@@ -0,0 +1,39 @@
+# git-subtree
+
+git-subtree allows subprojects to be included within a sub-directory of a main project, optionally including the sub-project's entire history.
+
+## Installation
+
+Choose **one** of the following ways to install git-subtree:
+
+1. Copy the file `git-subtree.sh` to where all other git scripts are stored.
+1. Run `install.sh` in a Git-enabled shell (that's "Git Bash" on Windows).
+1. Run `make install` in a Cygwin-enabled shell.
+
+Any *one* of these actions makes the `git subtree` command available (note: space instead of dash).
+
+To additionally install the man page:
+
+    make doc
+    cp git-subtree.1 /usr/share/man/man1/
+
+
+## Usage
+
+See `git-subtree.txt` for details.
+
+## Known issues
+
+See `todo`.
+
+## License
+
+You may use this software under the terms of the GNU General Public License (GPL), Version 2.
+
+See `COPYING`.
+
+## Credits
+
+Originally authored by Avery Pennarun, <http://apenwarr.ca/log>
+
+Please do not contact the author using github mail. Instead, <mailto:[email protected]>

git-subtree.txt

@@ -269,7 +269,7 @@ git-extensions repository in ~/git-extensions/:
 name
 
 You can omit the --squash flag, but doing so will increase the number
-of commits that are incldued in your local repository.
+of commits that are included in your local repository.
 
 We now have a ~/git-extensions/git-subtree directory containing code
 from the master branch of git://github.com/apenwarr/git-subtree.git
@@ -356,6 +356,44 @@ Then push the new branch onto the new empty repository:
 	$ git push <new-repo> split:master
 
 
+EXAMPLE 4. Re-integrate an already extracted subtree
+----------------------------------------------------
+Suppose you have extracted a sub-directory containing a library into an own
+repository through other means (without git-subtree) already, but it still
+exists in your mainline/original repository.  Here's how you re-integrate
+that back into your source/mainline:
+
+Let's assume that 'master' is our mainline branch in the original repo,
+containing the library in the lib/ sub-directory, which we want to split into
+a new 'class' branch and rejoin afterwards.
+
+First, split the local library into an own branch:
+
+  $ git checkout master
+  $ git subtree split --prefix=lib --rejoin -b split
+
+Second, add the library's existing upstream repo as remote 'vendor'.  To
+achieve an identical history, we checkout the upstream master into 'library',
+merge the history of 'split' into it, and push the result upstream:
+
+  $ git remote add vendor [email protected]:vendor/library.git
+  $ git fetch vendor
+  $ git checkout -b library vendor/master
+  $ git merge split
+  $ git push vendor library:master
+
+Third, merge any upstream library changes into your mainline:
+
+  $ git checkout master
+  $ git subtree merge --prefix=lib library
+  $ git push origin master
+
+To push changes in your local library to the vendor repo in the future, it's
+as simple as:
+
+  $ git subtree push --prefix=lib vendor master
+
+
 AUTHOR
 ------
 Written by Avery Pennarun <[email protected]>