Ben Knoble [off-list ref] writes:

quoted

Le 11 août 2025 à 05:29, Karthik Nayak [off-list ref] a écrit :

"Julia Evans via GitGitGadget" [off-list ref] writes:

quoted

Signed-off-by: Julia Evans <redacted>
---
Documentation/git-rebase.adoc | 49 ++++++++++++++++-------------------
1 file changed, 23 insertions(+), 26 deletions(-)

diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
index 956d3048f5a6..449f01fba560 100644
--- a/Documentation/git-rebase.adoc
+++ b/Documentation/git-rebase.adoc

@@ -16,6 +16,29 @@ SYNOPSIS

DESCRIPTION
-----------
+Transplant a series of commits onto a different starting point.
+
+For example, imagine that you have been working on the `topic` branch in this
+history, and you want to "catch up" to the work done on the `master` branch.
+
+------------
+          A---B---C topic
+         /
+    D---E---F---G master
+------------
+
+You want to transplant the commits you made on `topic` since it diverged from
+`master` (i.e. A, B, and C), on top of the current `master`.  You can do this
+by running `git rebase master` while the `topic` branch is checked out.  If you
+want to rebase `topic` while on another branch, `git rebase master topic` is a
+shortcut for `git checkout topic && git rebase master`.
+

Nit: now that `git-switch(1)` is no longer experimental, we should start
recommending it over `git-checkout(1)` as necessary. So perhaps, we
could s/checkout/switch here?

Junio previously recommended checkout (a prior version used switch): I suspect because checkout will detach head without extra syntax (where switch will not)?

I totally missed that, that makes sense!