In Mercurial what's the difference between hg graft and hg rebase

Question

I know Rebase is a (bundled) extension, while Graft is a core feature (that replaced the Transplant (bundled) extension).

graft is documented as:

copy changes from other branches onto the current branch

This command uses Mercurial's merge logic to copy individual changes from other branches without merging branches in the history graph. This is sometimes known as 'backporting' or 'cherry-picking'.

rebase is documented as:

Rebase allows moving commits around in Mercurial's history (using a series of internal merges). This has many uses:

• moving changesets between branches
• "linearizing" history
• reordering changesets
• collapsing multiple changes into one changeset

Both seem to use merging to move or copy changesets between branches.

Graft copies. Rebase moves. But rebase --keep copies.

So often it seems I can accomplish my goal of copying a changeset either way. Does it matter which one I use? When should I prefer one over the other?

E.g. should graft only be used when copying to a different named branch? Or only when there's just a single changeset?

---

Edit: Could it be that rebase is a potentially unsafe superset of graft, but can only be used with draft changesets during development for editing local history, while graft is a safe subset of rebase that can be used with public changesets during maintenance for backporting?

Solution

hg graft allows "cherry-picking," as you noted in your question. For example, you can run hg graft -D "2085::2093 and not 2091" to copy only some changes from another revision. By comparison, hg rebase (with or without --keep) will grab whatever changeset you specify and all of its decendant changes.

Also, rebase allows you to collapse changesets (with --collapse). As far as I can tell, graft does not.

One more difference I have noticed: hg graft --edit 123 lets you graft revision 123 to the working directory and edit the commit message. I can't find an hg rebase equivalent. I should point out, though, that hg histedit also allows for editing the commit message while rebasing.

There are probably other differences that I am not thinking of. SO community: feel free to point those out in the comments, and I will happily revise this answer to make it more complete.

See the graft documentation and the Rebase Extension documentation for more details.