diff options
Diffstat (limited to 'contrib/subtree/git-subtree.txt')
| -rw-r--r-- | contrib/subtree/git-subtree.txt | 207 |
1 files changed, 96 insertions, 111 deletions
diff --git a/contrib/subtree/git-subtree.txt b/contrib/subtree/git-subtree.txt index c5bce41ac7..54e4b4a243 100644 --- a/contrib/subtree/git-subtree.txt +++ b/contrib/subtree/git-subtree.txt @@ -10,8 +10,9 @@ SYNOPSIS -------- [verse] 'git subtree' add -P <prefix> <commit> -'git subtree' pull -P <prefix> <repository> <refspec...> -'git subtree' push -P <prefix> <repository> <refspec...> +'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>] @@ -67,7 +68,7 @@ COMMANDS -------- add:: Create the <prefix> subtree by importing its contents - from the given <refspec> or <repository> and remote <refspec>. + 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 @@ -80,22 +81,21 @@ merge:: 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. ++ +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 commit from the specified remote + 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 refspec. This can be used to push your + repository and ref. This can be used to push your subtree to different branches of the remote repository. split:: @@ -106,21 +106,19 @@ split:: 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 (ie. 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. ++ +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 @@ -150,109 +148,96 @@ 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 - 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. ++ +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. ++ +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. ++ +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. ++ +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. ++ +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. ++ +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 @@ -269,7 +254,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 |