From 375ebbab6a2d61c23134a413ad7346f1ef46c18d Mon Sep 17 00:00:00 2001 From: Vanya at notebook Date: Thu, 12 Aug 2010 18:21:31 +0300 Subject: [PATCH 1/7] doc: fixing a typo --- git-subtree.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/git-subtree.txt b/git-subtree.txt index dbcba31..a30293d 100644 --- a/git-subtree.txt +++ b/git-subtree.txt @@ -19,7 +19,7 @@ SYNOPSIS DESCRIPTION ----------- -git subtree allows you to include an subproject in your +git subtree allows you to include a subproject in your own repository as a subdirectory, optionally including the subproject's entire history. For example, you could include the source code for a library as a subdirectory of your From cc61a8a046dbe10145cf46172a904c9ccfe3fe7b Mon Sep 17 00:00:00 2001 From: Vanya at notebook Date: Thu, 12 Aug 2010 19:54:55 +0300 Subject: [PATCH 2/7] docs: Description, synopsys, options and examples changes. Description: Made the difference from submodules and the subtree merge strategy clearer. Synopsys and options: Synchronize with 'git subtree -h' output. I hope, properly. Examples: Added example descriptions in captions. Small fixes. Signed-off-by: John Yani --- git-subtree.txt | 112 +++++++++++++++++++++++++++++------------------- 1 file changed, 69 insertions(+), 43 deletions(-) diff --git a/git-subtree.txt b/git-subtree.txt index a30293d..18a9af5 100644 --- a/git-subtree.txt +++ b/git-subtree.txt @@ -3,50 +3,55 @@ git-subtree(1) NAME ---- -git-subtree - add, merge, and split subprojects stored in subtrees +git-subtree - Merge subtrees together and split repository into subtrees SYNOPSIS -------- [verse] -'git subtree' add --prefix= -'git subtree' pull --prefix= -'git subtree' push --prefix= -'git subtree' add --prefix= -'git subtree' merge --prefix= -'git subtree' split --prefix= - +'git subtree' add -P |--prefix= +'git subtree' pull -P |--prefix= +'git subtree' push -P |--prefix= +'git subtree' merge -P |--prefix= +'git subtree' split -P |--prefix= [OPTIONS] [] + DESCRIPTION ----------- -git subtree allows you to include a subproject in your -own repository as a subdirectory, optionally including the -subproject's entire history. For example, you could -include the source code for a library as a subdirectory of your -application. - -You can also extract the entire history of a subdirectory from -your project and make it into a standalone project. For -example, if a library you made for one application ends up being -useful elsewhere, you can extract its entire history and publish -that as its own git repository, without accidentally -intermingling the history of your application project. +Subtrees allow subprojects to be included within a subdirectory +of the main project, optionally including the subproject's +entire history. -Most importantly, you can alternate back and forth between these -two operations. If the standalone library gets updated, you can +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. + +They are neither not to be confused with using the subtree merge +strategy. The main difference is that, besides merging +of the other project as a subdirectory, you can also extract the +entire history of a subdirectory from your project and make it +into a standalone project. Unlike the subtree merge strategy +you can alternate back and forth between these +two operations. If the standalone library gets updated, you can automatically merge the changes into your project; if you update the library inside your project, you can "split" the changes back out again and merge them back into the library project. -Unlike the 'git submodule' command, git subtree doesn't produce -any special constructions (like .gitmodule files or gitlinks) in -your repository, and doesn't require end-users of your -repository to do anything special or to understand how subtrees -work. A subtree is just another subdirectory and can be -committed to, branched, and merged along with your project in -any way you want. +For example, if a library you made for one application ends up being +useful elsewhere, you can extract its entire history and publish +that as its own git repository, without accidentally +intermingling the history of your application project. +[TIP] In order to keep your commit messages clean, we recommend that people split their commits between the subtrees and the main project as much as possible. That is, if you make a change that @@ -128,20 +133,29 @@ OPTIONS --debug:: Produce even more unnecessary output messages on stderr. +-P :: --prefix=:: Specify the path in the repository to the subtree you - want to manipulate. This option is currently mandatory + want to manipulate. This option is mandatory for all commands. +-m :: +--message=:: + This option is only valid for add, merge and pull (unsure). + Specify as the commit message for the merge commit. -OPTIONS FOR add, merge, AND pull --------------------------------- + +OPTIONS FOR add, merge, push, pull +---------------------------------- --squash:: + This option is only valid for add, merge, push and pull + commands. + Instead of merging the entire history from the subtree project, produce only a single commit that contains all the differences you want to merge, and then merge that new commit into your project. - + Using this option helps to reduce log clutter. People rarely want to see every change that happened between v1.0 and v1.1 of the library they're using, since none of the @@ -169,6 +183,8 @@ OPTIONS FOR add, merge, AND pull OPTIONS FOR split ----------------- --annotate=:: + This option is only valid for the split command. + When generating synthetic history, add as a prefix to each commit message. Since we're creating new commits with the same commit message, but possibly @@ -184,12 +200,16 @@ OPTIONS FOR split -b :: --branch=:: + This option is only valid for the split command. + After generating the synthetic history, create a new branch called that contains the new history. This is suitable for immediate pushing upstream. must not already exist. --ignore-joins:: + This option is only valid for the split command. + If you use '--rejoin', git subtree attempts to optimize its history reconstruction to generate only the new commits since the last '--rejoin'. '--ignore-join' @@ -198,6 +218,8 @@ OPTIONS FOR split long time. --onto=:: + This option is only valid for the split command. + If your subtree was originally imported using something other than git subtree, its history may not match what git subtree is expecting. In that case, you can specify @@ -210,6 +232,8 @@ OPTIONS FOR split this option. --rejoin:: + This option is only valid for the split command. + After splitting, merge the newly created synthetic history back into your main project. That way, future splits can search only the part of history that has @@ -231,8 +255,8 @@ OPTIONS FOR split subproject's history to be part of your project anyway. -EXAMPLE 1 ---------- +EXAMPLE 1. Add command +---------------------- Let's assume that you have a local repository that you would like to add an external vendor library to. In this case we will add the git-subtree repository as a subdirectory of your already existing @@ -251,8 +275,8 @@ We now have a ~/git-extensions/git-subtree directory containing code from the master branch of git://github.com/apenwarr/git-subtree.git in our git-extensions repository. -EXAMPLE 2 ---------- +EXAMPLE 2. Extract a subtree using commit, merge and pull +--------------------------------------------------------- Let's use the repository for the git source code as an example. First, get your own copy of the git.git repository: @@ -312,22 +336,24 @@ the standard gitweb: git log gitweb-latest..$(git subtree split --prefix=gitweb) -EXAMPLE 3 ---------- +EXAMPLE 3. Extract a subtree using branch +----------------------------------------- Suppose you have a source directory with many files and subdirectories, and you want to extract the lib directory to its own git project. Here's a short way to do it: First, make the new repository wherever you want: - - git init --bare + + $ + $ git init --bare Back in your original directory: - git subtree split --prefix=lib --annotate="(split)" -b split + + $ git subtree split --prefix=lib --annotate="(split)" -b split Then push the new branch onto the new empty repository: - git push split:master + $ git push split:master AUTHOR From 75ca6bbbfb84162be8e726b4d454da04013ff438 Mon Sep 17 00:00:00 2001 From: Thomas Van Doren Date: Tue, 13 Dec 2011 16:52:43 -0800 Subject: [PATCH 3/7] Add info about `make doc` and make install.sh executable. --- INSTALL | 2 +- install.sh | 0 2 files changed, 1 insertion(+), 1 deletion(-) mode change 100644 => 100755 install.sh diff --git a/INSTALL b/INSTALL index 81ac702..7c04c1b 100644 --- a/INSTALL +++ b/INSTALL @@ -16,7 +16,7 @@ make install That will make a 'git subtree' (note: space instead of dash) command available. See the file git-subtree.txt for more. -You can also install the man page by doing: +You can also install the man page by doing (requires asciidoc): make doc cp git-subtree.1 /usr/share/man/man1/ diff --git a/install.sh b/install.sh old mode 100644 new mode 100755 From aa3fce83a85c20f812c17a002518296317ab2fd7 Mon Sep 17 00:00:00 2001 From: sun Date: Thu, 15 Dec 2011 00:22:15 +0100 Subject: [PATCH 4/7] Renamed README to README.md for Markdown support. --- README => README.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename README => README.md (100%) diff --git a/README b/README.md similarity index 100% rename from README rename to README.md From 2a39002fcc0af00ce2e7685e33081003a1f50f00 Mon Sep 17 00:00:00 2001 From: sun Date: Thu, 15 Dec 2011 00:27:32 +0100 Subject: [PATCH 5/7] Incorporated INSTALL into README.md. --- INSTALL | 22 ---------------------- README.md | 41 ++++++++++++++++++++++++++++++++++++----- 2 files changed, 36 insertions(+), 27 deletions(-) delete mode 100644 INSTALL diff --git a/INSTALL b/INSTALL deleted file mode 100644 index 81ac702..0000000 --- a/INSTALL +++ /dev/null @@ -1,22 +0,0 @@ - -HOW TO INSTALL git-subtree -========================== - -You simply need to copy the file 'git-subtree.sh' to where -the rest of the git scripts are stored. - -From the Git bash window just run: - -install.sh - -Or if you have the full Cygwin installed, you can use make: - -make install - -That will make a 'git subtree' (note: space instead of dash) command -available. See the file git-subtree.txt for more. - -You can also install the man page by doing: - - make doc - cp git-subtree.1 /usr/share/man/man1/ diff --git a/README.md b/README.md index c686b4a..94e8f30 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,39 @@ +# git-subtree -Please read git-subtree.txt for documentation. +git-subtree allows subprojects to be included within a sub-directory of a main project, optionally including the sub-project's entire history. -Please don't contact me using github mail; it's slow, ugly, and worst of -all, redundant. Email me instead at apenwarr@gmail.com and I'll be happy to -help. +## Installation -Avery +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. +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, + +Please do not contact the author using github mail. Instead, From 43c1af02da8f995f84802a88d6bdc8e7a3becdf8 Mon Sep 17 00:00:00 2001 From: sun Date: Thu, 15 Dec 2011 01:22:49 +0100 Subject: [PATCH 6/7] Clarified Git-enabled shell for Windows. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 94e8f30..4c331e6 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ git-subtree allows subprojects to be included within a sub-directory of a main p 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. +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). From 049db9ea1b83afc2113e30f2abdfaeee3184e081 Mon Sep 17 00:00:00 2001 From: Paul Cartwright Date: Thu, 27 Jan 2011 22:33:06 +0800 Subject: [PATCH 7/7] spell checking --- git-subtree.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/git-subtree.txt b/git-subtree.txt index 0c44fda..fd188a8 100644 --- a/git-subtree.txt +++ b/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