Documentation: sync git.txt command list and manual page title
[git/git.git] / Documentation / git-rebase.txt
1 git-rebase(1)
2 =============
3
4 NAME
5 ----
6 git-rebase - Forward-port local commits to the updated upstream head
7
8 SYNOPSIS
9 --------
10 'git-rebase' [-v] [--merge] [--onto <newbase>] <upstream> [<branch>]
11
12 'git-rebase' --continue | --skip | --abort
13
14 DESCRIPTION
15 -----------
16 git-rebase replaces <branch> with a new branch of the same name. When
17 the --onto option is provided the new branch starts out with a HEAD equal
18 to <newbase>, otherwise it is equal to <upstream>. It then attempts to
19 create a new commit for each commit from the original <branch> that does
20 not exist in the <upstream> branch.
21
22 It is possible that a merge failure will prevent this process from being
23 completely automatic. You will have to resolve any such merge failure
24 and run `git rebase --continue`. Another option is to bypass the commit
25 that caused the merge failure with `git rebase --skip`. To restore the
26 original <branch> and remove the .dotest working files, use the command
27 `git rebase --abort` instead.
28
29 Note that if <branch> is not specified on the command line, the currently
30 checked out branch is used.
31
32 Assume the following history exists and the current branch is "topic":
33
34 ------------
35 A---B---C topic
36 /
37 D---E---F---G master
38 ------------
39
40 From this point, the result of either of the following commands:
41
42
43 git-rebase master
44 git-rebase master topic
45
46 would be:
47
48 ------------
49 A'--B'--C' topic
50 /
51 D---E---F---G master
52 ------------
53
54 The latter form is just a short-hand of `git checkout topic`
55 followed by `git rebase master`.
56
57 Here is how you would transplant a topic branch based on one
58 branch to another, to pretend that you forked the topic branch
59 from the latter branch, using `rebase --onto`.
60
61 First let's assume your 'topic' is based on branch 'next'.
62 For example feature developed in 'topic' depends on some
63 functionality which is found in 'next'.
64
65 ------------
66 o---o---o---o---o master
67 \
68 o---o---o---o---o next
69 \
70 o---o---o topic
71 ------------
72
73 We would want to make 'topic' forked from branch 'master',
74 for example because the functionality 'topic' branch depend on
75 got merged into more stable 'master' branch, like this:
76
77 ------------
78 o---o---o---o---o master
79 | \
80 | o'--o'--o' topic
81 \
82 o---o---o---o---o next
83 ------------
84
85 We can get this using the following command:
86
87 git-rebase --onto master next topic
88
89
90 Another example of --onto option is to rebase part of a
91 branch. If we have the following situation:
92
93 ------------
94 H---I---J topicB
95 /
96 E---F---G topicA
97 /
98 A---B---C---D master
99 ------------
100
101 then the command
102
103 git-rebase --onto master topicA topicB
104
105 would result in:
106
107 ------------
108 H'--I'--J' topicB
109 /
110 | E---F---G topicA
111 |/
112 A---B---C---D master
113 ------------
114
115 This is useful when topicB does not depend on topicA.
116
117 In case of conflict, git-rebase will stop at the first problematic commit
118 and leave conflict markers in the tree. You can use git diff to locate
119 the markers (<<<<<<) and make edits to resolve the conflict. For each
120 file you edit, you need to tell git that the conflict has been resolved,
121 typically this would be done with
122
123
124 git update-index <filename>
125
126
127 After resolving the conflict manually and updating the index with the
128 desired resolution, you can continue the rebasing process with
129
130
131 git rebase --continue
132
133
134 Alternatively, you can undo the git-rebase with
135
136
137 git rebase --abort
138
139 OPTIONS
140 -------
141 <newbase>::
142 Starting point at which to create the new commits. If the
143 --onto option is not specified, the starting point is
144 <upstream>.
145
146 <upstream>::
147 Upstream branch to compare against.
148
149 <branch>::
150 Working branch; defaults to HEAD.
151
152 --continue::
153 Restart the rebasing process after having resolved a merge conflict.
154
155 --abort::
156 Restore the original branch and abort the rebase operation.
157
158 --skip::
159 Restart the rebasing process by skipping the current patch.
160
161 --merge::
162 Use merging strategies to rebase. When the recursive (default) merge
163 strategy is used, this allows rebase to be aware of renames on the
164 upstream side.
165
166 -s <strategy>, \--strategy=<strategy>::
167 Use the given merge strategy; can be supplied more than
168 once to specify them in the order they should be tried.
169 If there is no `-s` option, a built-in list of strategies
170 is used instead (`git-merge-recursive` when merging a single
171 head, `git-merge-octopus` otherwise). This implies --merge.
172
173 -v, \--verbose::
174 Display a diffstat of what changed upstream since the last rebase.
175
176 include::merge-strategies.txt[]
177
178 NOTES
179 -----
180 When you rebase a branch, you are changing its history in a way that
181 will cause problems for anyone who already has a copy of the branch
182 in their repository and tries to pull updates from you. You should
183 understand the implications of using 'git rebase' on a repository that
184 you share.
185
186 When the git rebase command is run, it will first execute a "pre-rebase"
187 hook if one exists. You can use this hook to do sanity checks and
188 reject the rebase if it isn't appropriate. Please see the template
189 pre-rebase hook script for an example.
190
191 You must be in the top directory of your project to start (or continue)
192 a rebase. Upon completion, <branch> will be the current branch.
193
194 Author
195 ------
196 Written by Junio C Hamano <junkio@cox.net>
197
198 Documentation
199 --------------
200 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
201
202 GIT
203 ---
204 Part of the gitlink:git[7] suite
205