Merge branch 'jk/remote-curl-an-array-in-struct-cannot-be-null' into maint
[gitweb.git] / contrib / subtree / git-subtree.txt
index 8272100ff56973417d426af33687f4e08c4a9e7b..54e4b4a24331045d97d92355b681b675048a5df7 100644 (file)
@@ -81,12 +81,11 @@ 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
@@ -107,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 (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.
++
+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
@@ -151,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