Easy to misinterpret --restore-descendants option

[joyously]

Now that there is a detailed writeup to answer the FAQ

how do I move the recent changes into another commit?

I'm wondering if the name of the option --restore-descendants could have a better name. Since it is on the restore command, it makes it seem like it is for making sure the descendants are also restored. But what I get from reading the details is that it actually preserves the descendants from being restored along with the target.
The overall explanation is fine, but the detail of that option confuses me.

Now, we jj restore the change lnvvtr to its state at commit b80. We use the --restore-descendants flag so that the file contents (AKA snapshot) of the "featureB" change is preserved.
Even though @- was modified, --restore-descendants preserved the contents of the current change

[ilyagr]

I'm hoping that the explanation of "More details on what --restore-descendants does clarify it a little. Quoting what I wrote,

When we ran the jj restore command, the working copy change @ was at commit 471 and @ was the only child of @-. In this situation,

jj restore --from b80 --into @- --restore-descendants

is equivalent to

jj restore --from b80 --into @-
jj restore --from 471 --into @

Would it help to add a comment # Restore the descendant to the second jj restore in the last code block?

---

This name is a bit of an uncomfortable compromise (TODO: find the relevant discussion).

Of the alternatives that we discussed, the two I remember are:

1. --verbatim-descendants, which I think I mildly prefer, but I think sounds unclear to others.
2. --reparent-descendants, which would go together with calling the operation of a rebase preserving snapshots "reparenting". (I'd call it "verbatim rebase")

I like --restore-descendants better than --reparent-descendants, but it might work if the notion of "reparenting" was strong in people's minds.

A very verbose name would be --preserve-descendant-snapshots. Perhaps we can think of more, and I may have forgotten some options that were discussed previously.

[joyously]

Would it help to add a comment # Restore the descendant to the second jj restore in the last code block?

No, this makes it more confusing.
I think the problem is that the command is restore and the option is also. It seems opposite to what you say that it's doing.

[ilyagr]

I'm not sure where it's currently implemented, but the same --restore-descendants option makes sense for many other commands¹: abandon, rebase -r, squash --into, probably others.

So, even if it's a bit confusing to repeat restore in the context of jj restore, consistency with the name for other commands might end up being more important. But, the confusion of jj restore --restore-descendants is still another reason to try to come up with a better name, if we can.

Footnotes

1. For the last two, it's a bit more confusing, since when --before or --after is used, we might want a separate option for the descendants of the target. For rebase, a third similar option makes sense, it would apply to the commit being moved, see the issue on "verbatim rebase". ↩