diff options
Diffstat (limited to 'third_party/git/contrib/subtree/git-subtree.txt')
| -rw-r--r-- | third_party/git/contrib/subtree/git-subtree.txt | 351 |
1 files changed, 0 insertions, 351 deletions
diff --git a/third_party/git/contrib/subtree/git-subtree.txt b/third_party/git/contrib/subtree/git-subtree.txt deleted file mode 100644 index 352deda69d..0000000000 --- a/third_party/git/contrib/subtree/git-subtree.txt +++ /dev/null @@ -1,351 +0,0 @@ -git-subtree(1) -============== - -NAME ----- -git-subtree - Merge subtrees together and split repository into subtrees - - -SYNOPSIS --------- -[verse] -'git subtree' add -P <prefix> <commit> -'git subtree' add -P <prefix> <repository> <ref> -'git subtree' pull -P <prefix> <repository> <ref> -'git subtree' push -P <prefix> <repository> <ref> -'git subtree' merge -P <prefix> <commit> -'git subtree' split -P <prefix> [OPTIONS] [<commit>] - - -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 .gitmodules 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 also not to be confused with using the subtree merge -strategy. The main difference is that, besides merging -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. - -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 -affects both the library and the main application, commit it in -two pieces. That way, when you split the library commits out -later, their descriptions will still make sense. But if this -isn't important to you, it's not *necessary*. git subtree will -simply leave out the non-library-related parts of the commit -when it splits it out into the subproject later. - - -COMMANDS --------- -add:: - Create the <prefix> subtree by importing its contents - from the given <commit> or <repository> and remote <ref>. - A new commit is created automatically, joining the imported - project's history with your own. With '--squash', imports - only a single commit from the subproject, rather than its - entire history. - -merge:: - Merge recent changes up to <commit> into the <prefix> - subtree. As with normal 'git merge', this doesn't - remove your own local changes; it just merges those - changes into the latest <commit>. With '--squash', - creates only one commit that contains all the changes, - rather than merging in the entire history. -+ -If you use '--squash', the merge direction doesn't always have to be -forward; you can use this command to go back in time from v2.5 to v2.4, -for example. If your merge introduces a conflict, you can resolve it in -the usual ways. - -pull:: - Exactly like 'merge', but parallels 'git pull' in that - it fetches the given ref from the specified remote - repository. - -push:: - Does a 'split' (see below) using the <prefix> supplied - and then does a 'git push' to push the result to the - repository and ref. This can be used to push your - subtree to different branches of the remote repository. - -split:: - Extract a new, synthetic project history from the - history of the <prefix> subtree. The new history - includes only the commits (including merges) that - affected <prefix>, and each of those commits now has the - contents of <prefix> at the root of the project instead - of in a subdirectory. Thus, the newly created history - is suitable for export as a separate git repository. -+ -After splitting successfully, a single commit id is printed to stdout. -This corresponds to the HEAD of the newly created tree, which you can -manipulate however you want. -+ -Repeated splits of exactly the same history are guaranteed to be -identical (i.e. to produce the same commit ids). Because of this, if -you add new commits and then re-split, the new commits will be attached -as commits on top of the history you generated last time, so 'git merge' -and friends will work as expected. -+ -Note that if you use '--squash' when you merge, you should usually not -just '--rejoin' when you split. - - -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. - - -OPTIONS FOR add, merge, push, pull ----------------------------------- ---squash:: - This option is only valid for add, merge, 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 interim versions were ever included in their -application. -+ -Using '--squash' also helps avoid problems when the same subproject is -included multiple times in the same project, or is removed and then -re-added. In such a case, it doesn't make sense to combine the -histories anyway, since it's unclear which part of the history belongs -to which subtree. -+ -Furthermore, with '--squash', you can switch back and forth between -different versions of a subtree, rather than strictly forward. 'git -subtree merge --squash' always adjusts the subtree to match the exactly -specified commit, even if getting to that commit would require undoing -some changes that were added earlier. -+ -Whether or not you use '--squash', changes made in your local repository -remain intact and can be later split and send upstream to the -subproject. - - -OPTIONS FOR split ------------------ ---annotate=<annotation>:: - This option is only valid for the split command. -+ -When generating synthetic history, add <annotation> as a prefix to each -commit message. Since we're creating new commits with the same commit -message, but possibly different content, from the original commits, this -can help to differentiate them and avoid confusion. -+ -Whenever you split, you need to use the same <annotation>, or else you -don't have a guarantee that the new re-created history will be identical -to the old one. That will prevent merging from working correctly. git -subtree tries to make it work anyway, particularly if you use --rejoin, -but it may not always be effective. - --b <branch>:: ---branch=<branch>:: - This option is only valid for the split command. -+ -After generating the synthetic history, create a new branch called -<branch> that contains the new history. This is suitable for immediate -pushing upstream. <branch> 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' disables this behaviour, forcing it to -regenerate the entire history. In a large project, this can take a long -time. - ---onto=<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 the commit id <onto> that corresponds to the -first revision of the subproject's history that was imported into your -project, and git subtree will attempt to build its history from there. -+ -If you used 'git subtree add', you should never need 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 been added since the most recent --rejoin. -+ -If your split commits end up merged into the upstream subproject, and -then you want to get the latest upstream version, this will allow git's -merge algorithm to more intelligently avoid conflicts (since it knows -these synthetic commits are already part of the upstream repository). -+ -Unfortunately, using this option results in 'git log' showing an extra -copy of every new commit that was created (the original, and the -synthetic one). -+ -If you do all your merges with '--squash', don't use '--rejoin' when you -split, because you don't want the subproject's history to be part of -your project anyway. - - -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 -git-extensions repository in ~/git-extensions/: - - $ git subtree add --prefix=git-subtree --squash \ - git://github.com/apenwarr/git-subtree.git master - -'master' needs to be a valid remote ref and can be a different branch -name - -You can omit the --squash flag, but doing so will increase the number -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 -in our git-extensions repository. - -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: - - $ git clone git://git.kernel.org/pub/scm/git/git.git test-git - $ cd test-git - -gitweb (commit 1130ef3) was merged into git as of commit -0a8f4f0, after which it was no longer maintained separately. -But imagine it had been maintained separately, and we wanted to -extract git's changes to gitweb since that time, to share with -the upstream. You could do this: - - $ git subtree split --prefix=gitweb --annotate='(split) ' \ - 0a8f4f0^.. --onto=1130ef3 --rejoin \ - --branch gitweb-latest - $ gitk gitweb-latest - $ git push git@github.com:whatever/gitweb.git gitweb-latest:master - -(We use '0a8f4f0^..' because that means "all the changes from -0a8f4f0 to the current version, including 0a8f4f0 itself.") - -If gitweb had originally been merged using 'git subtree add' (or -a previous split had already been done with --rejoin specified) -then you can do all your splits without having to remember any -weird commit ids: - - $ git subtree split --prefix=gitweb --annotate='(split) ' --rejoin \ - --branch gitweb-latest2 - -And you can merge changes back in from the upstream project just -as easily: - - $ git subtree pull --prefix=gitweb \ - git@github.com:whatever/gitweb.git master - -Or, using '--squash', you can actually rewind to an earlier -version of gitweb: - - $ git subtree merge --prefix=gitweb --squash gitweb-latest~10 - -Then make some changes: - - $ date >gitweb/myfile - $ git add gitweb/myfile - $ git commit -m 'created myfile' - -And fast forward again: - - $ git subtree merge --prefix=gitweb --squash gitweb-latest - -And notice that your change is still intact: - - $ ls -l gitweb/myfile - -And you can split it out and look at your changes versus -the standard gitweb: - - git log gitweb-latest..$(git subtree split --prefix=gitweb) - -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: - - $ <go to the new location> - $ git init --bare - -Back in your original directory: - - $ git subtree split --prefix=lib --annotate="(split)" -b split - -Then push the new branch onto the new empty repository: - - $ git push <new-repo> split:master - - -AUTHOR ------- -Written by Avery Pennarun <apenwarr@gmail.com> - - -GIT ---- -Part of the linkgit:git[1] suite |