On Wed, Mar 05, 2014 at 11:18:17AM -0800, Junio C Hamano wrote: > Jeff King <peff@xxxxxxxx> writes: > > > On Wed, Mar 05, 2014 at 10:49:24AM -0800, Junio C Hamano wrote: > > > >> ... the plan, at least in my mind, has always been exactly that: grafts > >> were a nice little attempt but is broken---if you really wanted to > >> muck with the history without rewriting (which is still discouraged, > >> by the way), do not use "graft", but use "replace". > > > > I certainly had in the back of my mind that grafts were a lesser form of > > "replace", and that eventually we could get rid of the former. Perhaps > > my question should have been: "why haven't we deprecated grafts yet?". > > Given that we discourage "grafts" strongly and "replace" less so > (but still discourage it), telling the users that biting the bullet > and rewriting the history is _the_ permanent solution, I think it is > understandable why nobody has bothered to. Perhaps the patch below would help discourage grafts more? The notable place in the documentation where grafts are still used is git-filter-branch.txt. But since the example there is about cementing rewritten history, it might be OK to leave. I used "outdated" below. We could also up the ante to "deprecated". -- >8 -- Subject: [PATCH] docs: mark info/grafts as outdated We should be encouraging people to use git-replace instead. Signed-off-by: Jeff King <peff@xxxxxxxx> --- Documentation/gitrepository-layout.txt | 4 ++++ Documentation/glossary-content.txt | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index aa03882..17d2ea6 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -176,6 +176,10 @@ info/grafts:: per line describes a commit and its fake parents by listing their 40-byte hexadecimal object names separated by a space and terminated by a newline. ++ +Note that the grafts mechanism is outdated and can lead to problems +transferring objects between repositories; see linkgit:git-replace[1] +for a more flexible and robust system to do the same thing. info/exclude:: This file, by convention among Porcelains, stores the diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 378306f..be0858c 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -176,6 +176,10 @@ current branch integrates with) obviously do not work, as there is no you can make Git pretend the set of <<def_parent,parents>> a <<def_commit,commit>> has is different from what was recorded when the commit was created. Configured via the `.git/info/grafts` file. ++ +Note that the grafts mechanism is outdated and can lead to problems +transferring objects between repositories; see linkgit:git-replace[1] +for a more flexible and robust system to do the same thing. [[def_hash]]hash:: In Git's context, synonym for <<def_object_name,object name>>. -- 1.8.5.2.500.g8060133 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html