Re: [PATCH v5 3/4] BreakingChanges: document removal of grafting

[Junio C Hamano <gitster@pobox.com>]

Patrick Steinhardt <ps@pks.im> writes:

> The grafting mechanism for objects has been deprecated in e650d0643b
> (docs: mark info/grafts as outdated, 2014-03-05), which is more than a
> decade ago. The mechanism can lead to hard-to-debug issues and has a
> superior replacement with replace refs.
>
> Follow through with the deprecation and mark grafts for removal in Git
> 3.0.
>
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
>  Documentation/BreakingChanges.txt | 8 ++++++++
>  1 file changed, 8 insertions(+)
>
> diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
> index 904857a636..b5088dcce2 100644
> --- a/Documentation/BreakingChanges.txt
> +++ b/Documentation/BreakingChanges.txt
> @@ -87,6 +87,14 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
>  
>  === Removals
>  
> +* Support for grafting commits has long been superseded by git-replace(1).
> +  Grafts are inferior to replacement refs as the mechanism can lead to
> +  hard-to-diagnose problems when transferring objects between repositories.

The replace refs will be transferred, but the graft is a purely
local mechanism and there is no way (other than by human
intervention) to communicate the graft entries across repositories.

That is the primary thing we should list as the reason why the
replace mechanism is a better alternative over the graft mechanism.

> +  They have been outdated since e650d0643b (docs: mark info/grafts as outdated,
> +  2014-03-05) and will be removed.
> ++
> +Cf. <20140304174806.GA11561@sigill.intra.peff.net>.
> +
>  == Superseded features that will not be deprecated
>  
>  Some features have gained newer replacements that aim to improve the design in