Cover grafting in the Git User's Manual

> The only mention of grafting in the manual is in the glossary:
> 
>     Grafts enables two otherwise different lines of development to
>     be joined together by recording fake ancestry information for
>     commits. This way you can make git pretend the set of parents
>     a commit has is different from what was recorded when the
>     commit was created. Configured via the .git/info/grafts file.
> 
> I believe it would be useful to cover this better, perhaps in chapter
> 5. Rewriting history and maintaining patch series.  It certainly would
> have saved me a few hours of digging.  I already understood enough of
> git to *know* that what I wanted must be possible (supply missing
> parents of merges in a repository imported with parsecvs), but I
> didn't know the magic keyword was graft.  I managed to figure it out
> >from the glossary, git-filter-branch(1) and GitWiki's GraftPoint page.
> 
> I'm neither writer nor git expert, but here's my try anyway:
> 
> Rewriting ancestry with grafts
> 
> Grafts enables two otherwise different lines of development to be
> joined together by recording fake ancestry information for commits.
> This way you can make git pretend the set of parents a commit has is
> different from what was recorded when the commit was created.
> 
> Why would you want to do that?  Say, you imported a repository from an
> SCM that doesn't record merges properly, e.g. CVS.  Grafts let you add
> the missing parents to the merge commits.  Or you switched your
> project to git by populating a new repository with current sources,
> and later decide you want more history.  Committing old versions is
> easy enough, but you also need to graft a parent to your original root
> commit.
> 
> Graft points are configured via the .git/info/grafts file.  It has one
> record per line describing a commit and its fake parents by listing
> object names separated by a space and terminated by a newline.
> 
>     <commit sha1> <parent sha1> [<parent sha1>]*
> 
> A graft point does not actually change its commit.  Nothing can.  What
> can be done is rewriting the commit and its descendants.
> git-filter-branch does that:
> 
>     $ cat .git/info/grafts
>     db5a561750ae87615719ae409d1f50c9dfc3fa71 08f2fa81d104b937c1f24c68f56e9d5039356764 8c231303bb995cbfdfd1c434a59a7c96ea2f0251
>     git-filter-branch HEAD ^08f2fa81d104b937c1f24c68f56e9d5039356764 ^8c231303bb995cbfdfd1c434a59a7c96ea2f0251
> 
> This rewrites history between head and the graft-point to include the
> grafted parents.

> On Wed, Nov 28, 2007 at 07:23:01PM +0100, Markus Armbruster wrote:
>> The only mention of grafting in the manual is in the glossary:
>> 
>>     Grafts enables two otherwise different lines of development to
>>     be joined together by recording fake ancestry information for
>>     commits. This way you can make git pretend the set of parents
>>     a commit has is different from what was recorded when the
>>     commit was created. Configured via the .git/info/grafts file.
>> 
>> I believe it would be useful to cover this better, perhaps in chapter
>> 5. Rewriting history and maintaining patch series.  It certainly would
>> have saved me a few hours of digging.  I already understood enough of
>> git to *know* that what I wanted must be possible (supply missing
>> parents of merges in a repository imported with parsecvs), but I
>> didn't know the magic keyword was graft.  I managed to figure it out
>> >from the glossary, git-filter-branch(1) and GitWiki's GraftPoint page.
>> 
>> I'm neither writer nor git expert, but here's my try anyway:
>> 
>> Rewriting ancestry with grafts
>> 
>> Grafts enables two otherwise different lines of development to be
>> joined together by recording fake ancestry information for commits.
>> This way you can make git pretend the set of parents a commit has is
>> different from what was recorded when the commit was created.
>> 
>> Why would you want to do that?  Say, you imported a repository from an
>> SCM that doesn't record merges properly, e.g. CVS.  Grafts let you add
>> the missing parents to the merge commits.  Or you switched your
>> project to git by populating a new repository with current sources,
>> and later decide you want more history.  Committing old versions is
>> easy enough, but you also need to graft a parent to your original root
>> commit.
>> 
>> Graft points are configured via the .git/info/grafts file.  It has one
>> record per line describing a commit and its fake parents by listing
>> object names separated by a space and terminated by a newline.
>> 
>>     <commit sha1> <parent sha1> [<parent sha1>]*
>> 
>> A graft point does not actually change its commit.  Nothing can.  What
>> can be done is rewriting the commit and its descendants.
>> git-filter-branch does that:
>> 
>>     $ cat .git/info/grafts
>>     db5a561750ae87615719ae409d1f50c9dfc3fa71 08f2fa81d104b937c1f24c68f56e9d5039356764 8c231303bb995cbfdfd1c434a59a7c96ea2f0251
>>     git-filter-branch HEAD ^08f2fa81d104b937c1f24c68f56e9d5039356764 ^8c231303bb995cbfdfd1c434a59a7c96ea2f0251
>> 
>> This rewrites history between head and the graft-point to include the
>> grafted parents.
>
> Did I overlook something or isn't
>
>      git-filter-branch HEAD ^db5a561750ae87615719ae409d1f50c9dfc3fa71
>
> what you are looking for? Only db5a56 could get rewritten and obviously
> all the commits having it as a parent.
>
> -Peter

> Peter Baumann <waste.manager@gmx.de> writes:
> 
> > On Wed, Nov 28, 2007 at 07:23:01PM +0100, Markus Armbruster wrote:
> >> The only mention of grafting in the manual is in the glossary:
> >> 
> >>     Grafts enables two otherwise different lines of development to
> >>     be joined together by recording fake ancestry information for
> >>     commits. This way you can make git pretend the set of parents
> >>     a commit has is different from what was recorded when the
> >>     commit was created. Configured via the .git/info/grafts file.
> >> 
> >> I believe it would be useful to cover this better, perhaps in chapter
> >> 5. Rewriting history and maintaining patch series.  It certainly would
> >> have saved me a few hours of digging.  I already understood enough of
> >> git to *know* that what I wanted must be possible (supply missing
> >> parents of merges in a repository imported with parsecvs), but I
> >> didn't know the magic keyword was graft.  I managed to figure it out
> >> >from the glossary, git-filter-branch(1) and GitWiki's GraftPoint page.
> >> 
> >> I'm neither writer nor git expert, but here's my try anyway:
> >> 
> >> Rewriting ancestry with grafts
> >> 
> >> Grafts enables two otherwise different lines of development to be
> >> joined together by recording fake ancestry information for commits.
> >> This way you can make git pretend the set of parents a commit has is
> >> different from what was recorded when the commit was created.
> >> 
> >> Why would you want to do that?  Say, you imported a repository from an
> >> SCM that doesn't record merges properly, e.g. CVS.  Grafts let you add
> >> the missing parents to the merge commits.  Or you switched your
> >> project to git by populating a new repository with current sources,
> >> and later decide you want more history.  Committing old versions is
> >> easy enough, but you also need to graft a parent to your original root
> >> commit.
> >> 
> >> Graft points are configured via the .git/info/grafts file.  It has one
> >> record per line describing a commit and its fake parents by listing
> >> object names separated by a space and terminated by a newline.
> >> 
> >>     <commit sha1> <parent sha1> [<parent sha1>]*
> >> 
> >> A graft point does not actually change its commit.  Nothing can.  What
> >> can be done is rewriting the commit and its descendants.
> >> git-filter-branch does that:
> >> 
> >>     $ cat .git/info/grafts
> >>     db5a561750ae87615719ae409d1f50c9dfc3fa71 08f2fa81d104b937c1f24c68f56e9d5039356764 8c231303bb995cbfdfd1c434a59a7c96ea2f0251
> >>     git-filter-branch HEAD ^08f2fa81d104b937c1f24c68f56e9d5039356764 ^8c231303bb995cbfdfd1c434a59a7c96ea2f0251
> >> 
> >> This rewrites history between head and the graft-point to include the
> >> grafted parents.
> >
> > Did I overlook something or isn't
> >
> >      git-filter-branch HEAD ^db5a561750ae87615719ae409d1f50c9dfc3fa71
> >
> > what you are looking for? Only db5a56 could get rewritten and obviously
> > all the commits having it as a parent.
> >
> > -Peter
> 
> That rewrites all commits reachable from HEAD that are not reachable
> >from db5a56.  In particular, it doesn't rewrite db5a56, does it?