[PATCH] replay: support replaying down from root commit

[PATCH] replay: support replaying down from root commit

[Toon Claes]

git-replay(1) doesn't allow replaying commits all the way down to the
root commit. Fix that.

Signed-off-by: Toon Claes <toon@iotcl.com>
---
These changes might conflict Siddharth's series[1] to add '--revert' to
git-replay(1), although resolving that should be trivial.

[1]: https://lore.kernel.org/git/20260313054035.26605-1-siddharthasthana31@gmail.com/
---
 replay.c                 | 18 ++++++++++--------
 t/t3650-replay-basics.sh | 10 +++++++---
 2 files changed, 17 insertions(+), 11 deletions(-)

diff --git a/replay.c b/replay.c
index a63f6714c4..63ff56552e 100644
--- a/replay.c
+++ b/replay.c
@@ -225,12 +225,18 @@ static struct commit *pick_regular_commit(struct repository *repo,
 	struct commit *base, *replayed_base;
 	struct tree *pickme_tree, *base_tree, *replayed_base_tree;
 
-	base = pickme->parents->item;
-	replayed_base = mapped_commit(replayed_commits, base, onto);
+	if (pickme->parents) {
+		base = pickme->parents->item;
+		replayed_base = mapped_commit(replayed_commits, base, onto);
+		base_tree = repo_get_commit_tree(repo, base);
+	} else {
+		base = NULL;
+		replayed_base = onto;
+		base_tree = lookup_tree(repo, repo->hash_algo->empty_tree);
+	}
 
 	replayed_base_tree = repo_get_commit_tree(repo, replayed_base);
 	pickme_tree = repo_get_commit_tree(repo, pickme);
-	base_tree = repo_get_commit_tree(repo, base);
 
 	merge_opt->branch1 = short_commit_name(repo, replayed_base);
 	merge_opt->branch2 = short_commit_name(repo, pickme);
@@ -293,8 +299,6 @@ int replay_revisions(struct rev_info *revs,
 	set_up_replay_mode(revs->repo, &revs->cmdline, opts->onto,
 			   &detached_head, &advance, &onto, &update_refs);
 
-	/* FIXME: Should allow replaying commits with the first as a root commit */
-
 	if (prepare_revision_walk(revs) < 0) {
 		ret = error(_("error preparing revisions"));
 		goto out;
@@ -309,9 +313,7 @@ int replay_revisions(struct rev_info *revs,
 		khint_t pos;
 		int hr;
 
-		if (!commit->parents)
-			die(_("replaying down from root commit is not supported yet!"));
-		if (commit->parents->next)
+		if (commit->parents && commit->parents->next)
 			die(_("replaying merge commits is not supported yet!"));
 
 		last_commit = pick_regular_commit(revs->repo, commit, replayed_commits,
diff --git a/t/t3650-replay-basics.sh b/t/t3650-replay-basics.sh
index a03f8f9293..9c55b62757 100755
--- a/t/t3650-replay-basics.sh
+++ b/t/t3650-replay-basics.sh
@@ -81,9 +81,13 @@ test_expect_success 'option --onto or --advance is mandatory' '
 	test_cmp expect actual
 '
 
-test_expect_success 'no base or negative ref gives no-replaying down to root error' '
-	echo "fatal: replaying down from root commit is not supported yet!" >expect &&
-	test_must_fail git replay --onto=topic1 topic2 2>actual &&
+test_expect_success 'replay down to root onto another branch' '
+	git replay --ref-action=print --onto main topic2 >result &&
+
+	test_line_count = 1 result &&
+
+	git log --format=%s $(cut -f 3 -d " " result) >actual &&
+	test_write_lines E D C M L B A >expect &&
 	test_cmp expect actual
 '
 

---
base-commit: ca1db8a0f7dc0dbea892e99f5b37c5fe5861be71
change-id: 20260317-toon-replay-down-to-root-d412048f1741

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

[Junio C Hamano]

Toon Claes <toon@iotcl.com> writes:

> git-replay(1) doesn't allow replaying commits all the way down to the
> root commit. Fix that.

OK.

> -	base = pickme->parents->item;
> -	replayed_base = mapped_commit(replayed_commits, base, onto);
> +	if (pickme->parents) {
> +		base = pickme->parents->item;
> +		replayed_base = mapped_commit(replayed_commits, base, onto);
> +		base_tree = repo_get_commit_tree(repo, base);

So, if we are replaying a commit with parent(s), we do the same as
before (base_tree used to be computed a bit later).  But ...

> +	} else {
> +		base = NULL;
> +		replayed_base = onto;
> +		base_tree = lookup_tree(repo, repo->hash_algo->empty_tree);
> +	}

... if we are replaying the root commit, there is no base (in
contrast to "the first parent of the original commit" used in the
other branch of this if-else construct).  We use an empty tree for
the base_tree, which is the natural thing to use to replay for a
root commit, of course.

I am not sure why replayed_base is computed differently, though?  Is
it because mapped_commit() would not work when base==NULL?

I have to wonder if the handling of that case should also be
encapsulated inside mapped_commit() helper, just like the helper
knows to "fallback" when the commit is not yet mapped, but that is
minor.  After all, if we drive that line of thought to the extreme,
we would end up making repo_get_commit_tree() to return an empty
tree object for base==NULL, too, which may be logical but it is
probably too much.

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

[Toon Claes]

Junio C Hamano <gitster@pobox.com> writes:

> Toon Claes <toon@iotcl.com> writes:
>
>> git-replay(1) doesn't allow replaying commits all the way down to the
>> root commit. Fix that.
>
> OK.
>
>> -	base = pickme->parents->item;
>> -	replayed_base = mapped_commit(replayed_commits, base, onto);
>> +	if (pickme->parents) {
>> +		base = pickme->parents->item;
>> +		replayed_base = mapped_commit(replayed_commits, base, onto);
>> +		base_tree = repo_get_commit_tree(repo, base);
>
> So, if we are replaying a commit with parent(s), we do the same as
> before (base_tree used to be computed a bit later).  But ...
>
>> +	} else {
>> +		base = NULL;
>> +		replayed_base = onto;
>> +		base_tree = lookup_tree(repo, repo->hash_algo->empty_tree);
>> +	}
>
> ... if we are replaying the root commit, there is no base (in
> contrast to "the first parent of the original commit" used in the
> other branch of this if-else construct).  We use an empty tree for
> the base_tree, which is the natural thing to use to replay for a
> root commit, of course.
>
> I am not sure why replayed_base is computed differently, though?  Is
> it because mapped_commit() would not work when base==NULL?

That's correct, mapped_commit() dereferences commit->object.oid.

> I have to wonder if the handling of that case should also be
> encapsulated inside mapped_commit() helper, just like the helper
> knows to "fallback" when the commit is not yet mapped

I'm fine either way, so I'll do that in v2.

> After all, if we drive that line of thought to the extreme, we would
> end up making repo_get_commit_tree() to return an empty tree object
> for base==NULL, too, which may be logical but it is probably too much.

Well, it's a bit annoying `struct commit::parents` is a `struct
commit_list`, so we have to first check that pointer before we can
dereference `item`, so that guard do we need anyway. So I agree it's too
much.

One other thing, in v2 I'm also fixing the merge ancestor label. For
root commits it will say "empty tree" instead of "parent of <commit>",
so conflict messages aren't misleading.

-- 
Cheers,
Toon

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

[Toon Claes]

git-replay(1) doesn't allow replaying commits all the way down to the
root commit. Fix that.

Signed-off-by: Toon Claes <toon@iotcl.com>
---
These changes might conflict Siddharth's series[1] to add '--revert' to
git-replay(1), although resolving that should be trivial.

[1]: https://lore.kernel.org/git/20260313054035.26605-1-siddharthasthana31@gmail.com/
---
Changes in v2:
- Add NULL pointer check for `commit` in mapped_commit().
- Change ancestor message to "empty tree" when replaying root commit.
- Link to v1: https://patch.msgid.link/20260317-toon-replay-down-to-root-v1-1-cb5c249e15fd@iotcl.com
---
 replay.c                 | 27 +++++++++++++++++----------
 t/t3650-replay-basics.sh | 10 +++++++---
 2 files changed, 24 insertions(+), 13 deletions(-)

diff --git a/replay.c b/replay.c
index a63f6714c4..92f2279156 100644
--- a/replay.c
+++ b/replay.c
@@ -209,7 +209,10 @@ static struct commit *mapped_commit(kh_oid_map_t *replayed_commits,
 				    struct commit *commit,
 				    struct commit *fallback)
 {
-	khint_t pos = kh_get_oid_map(replayed_commits, commit->object.oid);
+	khint_t pos;
+	if (!commit)
+		return fallback;
+	pos = kh_get_oid_map(replayed_commits, commit->object.oid);
 	if (pos == kh_end(replayed_commits))
 		return fallback;
 	return kh_value(replayed_commits, pos);
@@ -225,16 +228,24 @@ static struct commit *pick_regular_commit(struct repository *repo,
 	struct commit *base, *replayed_base;
 	struct tree *pickme_tree, *base_tree, *replayed_base_tree;
 
-	base = pickme->parents->item;
-	replayed_base = mapped_commit(replayed_commits, base, onto);
+	if (pickme->parents) {
+		base = pickme->parents->item;
+		base_tree = repo_get_commit_tree(repo, base);
+	} else {
+		base = NULL;
+		base_tree = lookup_tree(repo, repo->hash_algo->empty_tree);
+	}
 
+	replayed_base = mapped_commit(replayed_commits, base, onto);
 	replayed_base_tree = repo_get_commit_tree(repo, replayed_base);
 	pickme_tree = repo_get_commit_tree(repo, pickme);
-	base_tree = repo_get_commit_tree(repo, base);
 
 	merge_opt->branch1 = short_commit_name(repo, replayed_base);
 	merge_opt->branch2 = short_commit_name(repo, pickme);
-	merge_opt->ancestor = xstrfmt("parent of %s", merge_opt->branch2);
+	if (pickme->parents)
+		merge_opt->ancestor = xstrfmt("parent of %s", merge_opt->branch2);
+	else
+		merge_opt->ancestor = xstrdup("empty tree");
 
 	merge_incore_nonrecursive(merge_opt,
 				  base_tree,
@@ -293,8 +304,6 @@ int replay_revisions(struct rev_info *revs,
 	set_up_replay_mode(revs->repo, &revs->cmdline, opts->onto,
 			   &detached_head, &advance, &onto, &update_refs);
 
-	/* FIXME: Should allow replaying commits with the first as a root commit */
-
 	if (prepare_revision_walk(revs) < 0) {
 		ret = error(_("error preparing revisions"));
 		goto out;
@@ -309,9 +318,7 @@ int replay_revisions(struct rev_info *revs,
 		khint_t pos;
 		int hr;
 
-		if (!commit->parents)
-			die(_("replaying down from root commit is not supported yet!"));
-		if (commit->parents->next)
+		if (commit->parents && commit->parents->next)
 			die(_("replaying merge commits is not supported yet!"));
 
 		last_commit = pick_regular_commit(revs->repo, commit, replayed_commits,
diff --git a/t/t3650-replay-basics.sh b/t/t3650-replay-basics.sh
index a03f8f9293..9c55b62757 100755
--- a/t/t3650-replay-basics.sh
+++ b/t/t3650-replay-basics.sh
@@ -81,9 +81,13 @@ test_expect_success 'option --onto or --advance is mandatory' '
 	test_cmp expect actual
 '
 
-test_expect_success 'no base or negative ref gives no-replaying down to root error' '
-	echo "fatal: replaying down from root commit is not supported yet!" >expect &&
-	test_must_fail git replay --onto=topic1 topic2 2>actual &&
+test_expect_success 'replay down to root onto another branch' '
+	git replay --ref-action=print --onto main topic2 >result &&
+
+	test_line_count = 1 result &&
+
+	git log --format=%s $(cut -f 3 -d " " result) >actual &&
+	test_write_lines E D C M L B A >expect &&
 	test_cmp expect actual
 '
 

---
base-commit: ca1db8a0f7dc0dbea892e99f5b37c5fe5861be71
change-id: 20260317-toon-replay-down-to-root-d412048f1741

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

[Junio C Hamano]

Toon Claes <toon@iotcl.com> writes:

> git-replay(1) doesn't allow replaying commits all the way down to the
> root commit. Fix that.
>
> Signed-off-by: Toon Claes <toon@iotcl.com>
> ---
> These changes might conflict Siddharth's series[1] to add '--revert' to
> git-replay(1), although resolving that should be trivial.

True.  This round looks great to me.  Will queue.

Shall we mark the topic for 'next' now?

Thanks.

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

[Christian Couder]

On Tue, Mar 24, 2026 at 8:56 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Toon Claes <toon@iotcl.com> writes:
>
> > git-replay(1) doesn't allow replaying commits all the way down to the
> > root commit. Fix that.
> >
> > Signed-off-by: Toon Claes <toon@iotcl.com>
> > ---
> > These changes might conflict Siddharth's series[1] to add '--revert' to
> > git-replay(1), although resolving that should be trivial.
>
> True.  This round looks great to me.  Will queue.
>
> Shall we mark the topic for 'next' now?

The patch looks good to me, but I wonder if the docs should be updated
somehow, especially to try to avoid confusion in case users don't
properly specify a range.

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.

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`.
+
 OPTIONS
 -------

?

And yeah currently `git replay` is a plumbing command that most
regular users shouldn't likely use, but I think Elijah's goal was to
eventually make it user friendly enough for advanced users with
stacked branches.

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

[Ben Knoble]

> Le 25 mars 2026 à 06:05, Christian Couder <christian.couder@gmail.com> a écrit :
> 
> On Tue, Mar 24, 2026 at 8:56 PM Junio C Hamano <gitster@pobox.com> wrote:
>> 
>> Toon Claes <toon@iotcl.com> writes:
>> 
>>> git-replay(1) doesn't allow replaying commits all the way down to the
>>> root commit. Fix that.
>>> 
>>> Signed-off-by: Toon Claes <toon@iotcl.com>
>>> ---
>>> These changes might conflict Siddharth's series[1] to add '--revert' to
>>> git-replay(1), although resolving that should be trivial.
>> 
>> True.  This round looks great to me.  Will queue.
>> 
>> Shall we mark the topic for 'next' now?
> 
> The patch looks good to me, but I wonder if the docs should be updated
> somehow, especially to try to avoid confusion in case users don't
> properly specify a range.
> 
> 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.

Having used replay in a large monorepo where I juggle many branches (so rebasing another in-flight topic without otherwise interrupting my work is valuable), I’ve made this mistake a few times. Some way of handling it more gracefully would be appreciated: perhaps the root case is rare enough to warrant an option or confirmation prompt (when attached interactively)?

> 
> 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`.
> +
> OPTIONS
> -------
> 
> ?
> 
> And yeah currently `git replay` is a plumbing command that most
> regular users shouldn't likely use, but I think Elijah's goal was to
> eventually make it user friendly enough for advanced users with
> stacked branches.
> 

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

[Toon Claes]

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

> On Tue, Mar 24, 2026 at 8:56 PM Junio C Hamano <gitster@pobox.com> wrote:
>>
>> Toon Claes <toon@iotcl.com> writes:
>>
>> > git-replay(1) doesn't allow replaying commits all the way down to the
>> > root commit. Fix that.
>> >
>> > Signed-off-by: Toon Claes <toon@iotcl.com>
>> > ---
>> > These changes might conflict Siddharth's series[1] to add '--revert' to
>> > git-replay(1), although resolving that should be trivial.
>>
>> True.  This round looks great to me.  Will queue.
>>
>> Shall we mark the topic for 'next' now?
>
> The patch looks good to me, but I wonder if the docs should be updated
> somehow, especially to try to avoid confusion in case users don't
> properly specify a range.
>
> For example, before this, `git replay --onto main topic` would fail,
> but emit "fatal: replaying down from root commit is not supported
> yet!".

I'm fixing that in a separate series.

> 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.
>
> 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`.
> +

Definitely would help, not sure it needs to be part of this series.

-- 
Cheers,
Toon

Re: Make git-replay(1) warn if revision-range isn't a range (was: Re: [PATCH v2] replay: support replaying down from root commit)

[Toon Claes]

Ben Knoble <ben.knoble@gmail.com> writes:

>> The patch looks good to me, but I wonder if the docs should be updated
>> somehow, especially to try to avoid confusion in case users don't
>> properly specify a range.
>> 
>> 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.
>
> Having used replay in a large monorepo where I juggle many branches
> (so rebasing another in-flight topic without otherwise interrupting my
> work is valuable), I’ve made this mistake a few times. Some way of
> handling it more gracefully would be appreciated: perhaps the root
> case is rare enough to warrant an option or confirmation prompt (when
> attached interactively)?

Yeah, there is definetily room for improvement here. But I consider that
outside the scope of this series and more like #leftoverbits.

-- 
Cheers,
Toon

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

[Toon Claes]

Toon Claes <toon@iotcl.com> writes:

> I'm fixing that in a separate series.

LOL, whoops I'm mixing up my own series. Sorry about that.

-- 
Cheers,
Toon

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

[Junio C Hamano]

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.

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

[Junio C Hamano]

Toon Claes <toon@iotcl.com> writes:

>> 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`.
>> +
>
> Definitely would help, not sure it needs to be part of this series.

Where else should the patch to add such a note to the documentation
go, though?  Without this patch, we do not is because the command
will not take such a command line.  With this patch that adds the
"now we allow replay to take a single tip commit and replay the
history leading to the tip all the way down to root" feature, the
note may become relevant.

So to me, it looks like it is either we will never add such a note
because it is irrelevant and everybody should know the consequence
of passing "topic", not "main..topic", or we will have to add such a
note as part of the series (if the note would help the readers).

Even though I am on the fence about the need for this specific note
in the documentation, it does not make sense to me to say "this will
help but we are not doing so here".

My comment on "might" in "What you might" in the thread still
applies, by the way.

Thanks.

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

[Christian Couder]

On Fri, Mar 27, 2026 at 5:45 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Toon Claes <toon@iotcl.com> writes:
>
> >> 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`.
> >> +
> >
> > Definitely would help, not sure it needs to be part of this series.
>
> Where else should the patch to add such a note to the documentation
> go, though?  Without this patch, we do not is because the command
> will not take such a command line.  With this patch that adds the
> "now we allow replay to take a single tip commit and replay the
> history leading to the tip all the way down to root" feature, the
> note may become relevant.
>
> So to me, it looks like it is either we will never add such a note
> because it is irrelevant and everybody should know the consequence
> of passing "topic", not "main..topic", or we will have to add such a
> note as part of the series (if the note would help the readers).
>
> Even though I am on the fence about the need for this specific note
> in the documentation, it does not make sense to me to say "this will
> help but we are not doing so here".
>
> My comment on "might" in "What you might" in the thread still
> applies, by the way.

Another approach with this is to consider that in the first place the
main issue is that `git replay` doesn't emit any error message when it
fails due to a conflict, which isn't user friendly.

So if we are about to fix that main issue in a separate patch or
series, and if we plan to emit something like the following in the
regular case:

"fatal: replaying failed due to conflict"

and something like the following when replaying from a root commit:

"fatal: replaying from root commit XXX failed due to conflict"

then I think it would alleviate the need for a doc update.

But anyway even if we are planning such an error message fix, I think
a doc update would be nice, either along with such an error message
fix or along with this patch which allows replaying from a root
commit.

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

[Junio C Hamano]

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

> So if we are about to fix that main issue in a separate patch or
> series, and if we plan to emit something like the following in the
> regular case:
>
> "fatal: replaying failed due to conflict"
>
> and something like the following when replaying from a root commit:
>
> "fatal: replaying from root commit XXX failed due to conflict"
>
> then I think it would alleviate the need for a doc update.

Hmph, what would you do to the other side (i.e., replay from some
specified boundary) of the message?  When the version of "git
replay" command a user who sees for the first time comes with the
ability to replay from a root on day one, "from root commit" is not
so special from "from these boundary commits", so I am not sure if
it makes sense to have such a message that treats the down-to-root
case any specially.

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

[Toon Claes]

Junio C Hamano <gitster@pobox.com> writes:

> Toon Claes <toon@iotcl.com> writes:
>
>>> 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`.
>>> +
>>
>> Definitely would help, not sure it needs to be part of this series.
>
> Where else should the patch to add such a note to the documentation
> go, though?

First let me clarify, I'm sorry but I posted that message because I was
messing up two of my patch series. Yes, that change (if made) should
belong to this series.

> Where else should the patch to add such a note to the documentation
> go, though?  Without this patch, we do not is because the command
> will not take such a command line.  With this patch that adds the
> "now we allow replay to take a single tip commit and replay the
> history leading to the tip all the way down to root" feature, the
> note may become relevant.
>
> So to me, it looks like it is either we will never add such a note
> because it is irrelevant and everybody should know the consequence
> of passing "topic", not "main..topic", or we will have to add such a
> note as part of the series (if the note would help the readers).
>
> Even though I am on the fence about the need for this specific note
> in the documentation, it does not make sense to me to say "this will
> help but we are not doing so here".

The git-replay(1) docs refer to "Specifying Ranges" in
git-rev-parse(1). The section itself is included from
Documentation/revisions.adoc. If I look at "Revision Range Summary":

    Revision Range Summary
    ----------------------
    '<rev>'::
    	Include commits that are reachable from <rev> (i.e. <rev> and
    	its ancestors).

Personally I would say that's clear enough, and it feels a redundant to
repeat ourselves in the git-replay(1) docs. It's basically the same as
for every other command (git-log(1) for example).

Now I can understand it can be confusing when you compare this to how
git-rebase(1) works. But if you ask me, using git-rebase(1) with
'--onto' is a bit awkward anyway.

Nevertheless, looking at what the git-replay(1) docs now say about the
'<revision-range>':

    <revision-range>::
    	Range of commits to replay; see "Specifying Ranges" in
    	linkgit:git-rev-parse[1]. In `--advance <branch>` mode, the
    	range should have a single tip, so that it's clear to which tip the
    	advanced <branch> should point. Any commits in the range whose
    	changes are already present in the branch the commits are being
    	replayed onto will be dropped.

The phrasing around dropping commits can cause confusion. We should say
instead empty commits are dropped.

One other thing to note though, in my other patch series I'm changing
the docs to use stuck form. I think that also helps to clarify the
argument to '--onto' isn't part of the revision range.

But to summarize: I'm not sure a documentation change is needed, but if
you insist, I'm attaching a fixup patch (it's based on
sa/replay-revert). I'm leaving it to Christian an Junio to decide
whether it should be included. I'm happy to take it to a separate series
if you consider that a better idea.

> Christian Couder <christian.couder@gmail.com> writes:
>
>> So if we are about to fix that main issue in a separate patch or
>> series, and if we plan to emit something like the following in the
>> regular case:
>>
>> "fatal: replaying failed due to conflict"
>>
>> and something like the following when replaying from a root commit:
>>
>> "fatal: replaying from root commit XXX failed due to conflict"
>>
>> then I think it would alleviate the need for a doc update.
>
> Hmph, what would you do to the other side (i.e., replay from some
> specified boundary) of the message?  When the version of "git
> replay" command a user who sees for the first time comes with the
> ability to replay from a root on day one, "from root commit" is not
> so special from "from these boundary commits", so I am not sure if
> it makes sense to have such a message that treats the down-to-root
> case any specially.

I agree, making a separate error message for when replaying down to root
seems a bit of an overkill.


Cheers, Toon

---

From: Toon Claes <toon@iotcl.com>
Date: Thu, 2 Apr 2026 10:52:59 +0200
Subject: [PATCH] fixup! Add support to git-replay down from root commit

---
 Documentation/git-replay.adoc | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
index 997097e420..fb73a57444 100644
--- a/Documentation/git-replay.adoc
+++ b/Documentation/git-replay.adoc
@@ -78,13 +78,15 @@ incompatible with `--contained` (which is a modifier for `--onto` only).
 The default mode can be configured via the `replay.refAction` configuration variable.
 
 <revision-range>::
-	Range of commits to replay; see "Specifying Ranges" in
-	linkgit:git-rev-parse[1]. In `--advance <branch>` or
-	`--revert <branch>` mode, the range should have a single tip,
-	so that it's clear to which tip the advanced or reverted
-	<branch> should point. Any commits in the range whose changes
-	are already present in the branch the commits are being
-	replayed onto will be dropped.
+	Each ref specified in the `<revision-range>` is replayed and updated
+	separately. All commits reachable from those refs are replayed and thus
+	if no dotted range notation is used or excluded revision is given, each
+	ref is replayed down to root.
+	Commits that end up being empty are dropped.
+	Only one positive ref is allowed when using `--advance <branch>` or
+	`--revert <branch>`.
+	Consult "Specifying Ranges" in linkgit:git-rev-parse[1] for more
+	information.
 
 :git-replay: 1
 include::rev-list-options.adoc[]
-- 
2.53.0.310.g728cabbaf7

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

[Junio C Hamano]

Toon Claes <toon@iotcl.com> writes:

> Junio C Hamano <gitster@pobox.com> writes:
> ...
>> Even though I am on the fence about the need for this specific note
>> in the documentation, ...
> ...
> But to summarize: I'm not sure a documentation change is needed, but if
> you insist, I'm attaching a fixup patch (it's based on
> sa/replay-revert). I'm leaving it to Christian an Junio to decide
> whether it should be included. I'm happy to take it to a separate series
> if you consider that a better idea.

As I already said, I am not enthusiastic about the "how about adding
something like this" Christian gave us and I think we can do without
it, so I'll leave it up to Christian ;-)

Thanks, all.

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

[Christian Couder]

On Thu, Apr 2, 2026 at 7:02 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Toon Claes <toon@iotcl.com> writes:
>
> > Junio C Hamano <gitster@pobox.com> writes:
> > ...
> >> Even though I am on the fence about the need for this specific note
> >> in the documentation, ...
> > ...
> > But to summarize: I'm not sure a documentation change is needed, but if
> > you insist, I'm attaching a fixup patch (it's based on
> > sa/replay-revert). I'm leaving it to Christian an Junio to decide
> > whether it should be included. I'm happy to take it to a separate series
> > if you consider that a better idea.
>
> As I already said, I am not enthusiastic about the "how about adding
> something like this" Christian gave us and I think we can do without
> it, so I'll leave it up to Christian ;-)

Let's do without it then. We can take care of this when we eventually
decide to emit error messages when `git replay` fails, which can be
addressed as a separate issue.