From: John Yani Date: Thu, 12 Aug 2010 16:54:55 +0000 (+0300) Subject: docs: Description, synopsys, options and examples changes. X-Git-Tag: v1.7.11-rc0~176^2~8 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=7f86ff0fe292a5061757f3ceaffdd992c5feaa9f;p=git.git 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 --- diff --git a/git-subtree.txt b/git-subtree.txt index a30293d60..18a9af501 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