Re: [PATCH v2] replay: support replaying down from root commit

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

Christian Couder <christian.couder@gmail.com> writes:

> For example, before this, `git replay --onto main topic` would fail,
> but emit "fatal: replaying down from root commit is not supported
> yet!". This would likely help users understand that they might need to
> properly specify a range like "main..topic" instead of 'topic".
>
> Now it would likely fail without any error message.

The fact that I do not quite understand the suggested change is a
very strong sign that people would be helped by a bit more
documentation ;-).

Depending on what is in "topic" and what "main" has, wouldn't it be
possible that the history leads to "topic" replay cleanly on top of
"main"?  And if there are problems (e.g., the replayed history may
want to add a file where "main"'s history already has contents with
a different ancestry sitting there, or the path may be taken by a
directory), wouldn't "git replay" fail loudly explaining what got
conflicted, instead of failing silently?

> Maybe something like the following could help:
>
> --- a/Documentation/git-replay.adoc
> +++ b/Documentation/git-replay.adoc
> @@ -23,6 +23,10 @@ instead get update commands that can be piped to
> `git update-ref --stdin`
>
>  THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
>
> +Note that `git replay --onto main topic` replays the topic branch starting
> +from the root commit, not from main. What you might want instead is
> +`git replay --onto main main..topic`.

To be helpful, "might want" needs to be accompanied by "if you want
to do X", I think.  In this case, that X probably is "recreate what
was done on 'topic' since it forked from 'main' on top of 'main'".

Thanks.