git-subtree: bug, and ideas for doc improvements

[Yann Dirson <dirson@bertin.fr>]

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,
-- 
Yann Dirson - Bertin Technologies