git-subtree: bug, and ideas for doc improvements

Hi Avery,

Here are a couple of remarks from trying to work out how to convert an imported-with-local-changes kernel to git-subtree.

* When reading the doc, it looks like my use case would require --onto,
  but although it is documented *when* to we are expected to use that
  flag, it is not explained *what* it does (which tends to make be both
  curious and nervous about it ;)

* In addition, describing "what git subtree is expecting" without
  --onto would probably be useful

* If I first run "split" without --onto, then "reset --hard HEAD^" and
  rerun the same split with an additional --onto, then:
  - although a new set of split commits is created, the new branch
    ref is set to the old one
  - the split then aborts saying that the new branch ref is not an
    ancestor
 => this does not happen if I remove the old branch ref first, so it
 does not look tied to the subtree-cache, only to the reachability of
 the old split branch ?  FWIW, old branch (without --onto) is named
 "linux-2.6" and new one (with --onto) is "linux-2.6b".

* If I run "split --onto=XXX" where XXX is as specified in the manpage
  "the first revision of the subproject's history that was imported
  into your project", then the split history looks exactly the same,
  appart from:
  - without --onto, the root of the split branch has no parent
  - with --onto, the split branch is forked off the specified commit,
    which is itself not split.  The "--onto" name makes that result
    understandable, but shouldn't the doc tell to use "the last commit
    before the subproject's history was imported into your project"
    instead ?

Best regards,

Well, things finally seem even more complicated: in my case, the tree is a bit more particular than what I originally thought:

* I finally understand I read the --onto description wrong.  It could
  surely be made easier to understand, by telling the user he first
  has to import the subproject history into the superproject repo
  first.  Adding an example of this would be of great use too.

* In my case the directory in which the kernel was originally located
  has since then been renamed, and git-subtree stops exploring the
  history at the rename commit, assuming the full import occured there.

  Maybe git-subtree can be taught to follow renames, but currently the
  way to handle that would seem to split in 2 steps:
  - checkout the revision before the move
  - split that part of history using the old name (without
    --rejoin, and with a different --branch name than intended in
    the end)
  - checkout the head to be split
  - split the remaining part, passing --onto the branch name that was
    passed to --branch in the first run

  However, if I try that, the root of the second split has no parent.
  I can use a graft and filter-branch - but there is either something
  else I did not understood incorrectly, or maybe a bug somewhere ?

Best regards,