doc: git-rebase: start with an example
- Start with an example that mirrors the example in the `git-merge` man page, to make it easier for folks to understand the difference between a rebase and a merge. - Mention that rebase can combine or reorder commits Signed-off-by: Julia Evans <julia@jvns.ca> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Julia Evans committed
Aug 23, 2025 at 00:42 UTC
f39a29c22ee5deb184517c99890bd749f2114a98
1 file changed
+26
-26
Documentation/git-rebase.adoc
+26
-26
@@ -16,6 +16,32 @@ SYNOPSIS
16
17
DESCRIPTION
18
-----------
19
+Transplant a series of commits onto a different starting point.
20
+You can also use `git rebase` to reorder or combine commits: see INTERACTIVE
21
+MODE below for how to do that.
22
+
23
+For example, imagine that you have been working on the `topic` branch in this
24
+history, and you want to "catch up" to the work done on the `master` branch.
25
+
26
+------------
27
+ A---B---C topic
28
+ /
29
+ D---E---F---G master
30
+------------
31
+
32
+You want to transplant the commits you made on `topic` since it diverged from
33
+`master` (i.e. A, B, and C), on top of the current `master`. You can do this
34
+by running `git rebase master` while the `topic` branch is checked out. If you
35
+want to rebase `topic` while on another branch, `git rebase master topic` is a
36
+shortcut for `git checkout topic && git rebase master`.
37
+
38
+------------
39
+ A'--B'--C' topic
40
+ /
41
+ D---E---F---G master
42
+------------
43
+
44
+
45
If `<branch>` is specified, `git rebase` will perform an automatic
46
`git switch <branch>` before doing anything else. Otherwise
47
it remains on the current branch.
@@ -58,32 +84,6 @@ that caused the merge failure with `git rebase --skip`. To check out the
84
original `<branch>` and remove the `.git/rebase-apply` working files, use
85
the command `git rebase --abort` instead.
86
61
-Assume the following history exists and the current branch is "topic":
62
-
63
-------------
64
- A---B---C topic
65
- /
66
- D---E---F---G master
67
-------------
68
-
69
-From this point, the result of either of the following commands:
70
-
71
-
72
- git rebase master
73
- git rebase master topic
74
-
75
-would be:
76
-
77
-------------
78
- A'--B'--C' topic
79
- /
80
- D---E---F---G master
81
-------------
82
-
83
-*NOTE:* The latter form is just a short-hand of `git checkout topic`
84
-followed by `git rebase master`. When rebase exits `topic` will
85
-remain the checked-out branch.
86
-
87
If the upstream branch already contains a change you have made (e.g.,
88
because you mailed a patch which was applied upstream), then that commit
89
will be skipped and warnings will be issued (if the 'merge' backend is