f8ded16 · git/git-reference · siGit Code & Deploy

@@ -0,0 +1,468 @@

1 +---

2 +layout: reference

3 +---

4 +

5 +<div class="box">

6 + <h2>

7 +

8 + <a target="new" href="http://progit.org/book/ch2-2.html">book</a>

9 +

10 + Branching and Merging

11 + </h2>

12 + <div class="block">

13 + Branching in Git is one of my favorite features. If you have used other

14 + version control systems, it's probably helpful to forget most of what you

15 + think about branches - in fact, it may be more helpful to think of them

16 + practically as contexts since that is how you will most often be

17 + using them. When you checkout different branches, you change contexts

18 + that you are working in and you can quickly context-switch back and forth

19 + between several different branches.

20 +

21 +

22 +

23 + In a nutshell you can create a branch with

24 + <code>git branch (branchname)</code>, switch into that context with

25 + <code>git checkout (branchname)</code>, record commit snapshots while

26 + in that context, then can switch back and forth easily. When you switch

27 + branches, Git replaces your working directory with the snapshot of the

28 + latest commit on that branch so you don't have to have multiple directories

29 + for multiple branches. You merge branches together with

30 + <code>git merge</code>. You can easily merge multiple times from the same

31 + branch over time, or alternately you can choose to delete a branch

32 + immediately after merging it.

33 +

34 +

35 + </div>

36 +</div>

37 +

38 +<div class="box">

39 + <h2>

40 +

41 + <a target="new" href="http://www.kernel.org/pub/software/scm/git/docs/git-branch.html">docs</a>

42 + <a target="new" href="http://progit.org/book/">book</a>

43 +

44 + <a name="branch">git branch</a>

45 + list, create and manage working contexts

46 + </h2>

47 +

48 +

49 +

50 + <h2>

51 +

52 + <a target="new" href="http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html">docs</a>

53 + <a target="new" href="http://progit.org/book/">book</a>

54 +

55 + <a name="checkout">git checkout</a>

56 + switch to a new branch context

57 + </h2>

58 +

59 + <div class="block">

60 + The <code>git branch</code> command is a general branch management tool

61 + for Git and can do several different things. We'll cover the basic ones

62 + that you'll use most - listing branches, creating branches and deleting

63 + branches. We will also cover basic <code>git checkout</code> here which

64 + switches you between your branches.

65 +

66 +

67 + <h4>

68 + git branch

69 + list your available branches

70 + </h4>

71 +

72 + Without arguments, <code>git branch</code> will list out the local

73 + branches that you have. The branch that you are currently working on will

74 + have a star next to it and if you have

75 + <a href="http://progit.org/book/ch7-1.html#colors_in_git">coloring turned on</a>,

76 + will show the current branch in green.

77 +

78 +

79 +<pre>

80 +$ git branch

81 +* master

82 +</pre>

83 +

84 + This means that we have a 'master' branch and we are currently on it.

85 + When you run <code>git init</code> it will automatically create a 'master'

86 + branch for you by default, however there is nothing special about the name -

87 + you don't actually have to have a 'master' branch but since it's the default

88 + that is created, most projects do.

89 +

90 +

91 + <h4>

92 + git branch (branchname)

93 + create a new branch

94 + </h4>

95 +

96 + So let's start by creating a new branch and switching to it. You can do

97 + that by running <code>git branch (branchname)</code>.

98 +

99 +<pre>

100 +$ git branch testing

101 +$ git branch

102 +* master

103 + testing

104 +</pre>

105 +

106 + Now we can see that we have a new branch. When you create a branch this

107 + way it creates the branch at your last commit so if you record some commits

108 + at this point and then switch to 'testing', it will revert your working

109 + directory context back to when you created the branch in the first place -

110 + you can think of it like a bookmark for where you currently are. Let's see

111 + this in action - we use <code>git checkout (branch)</code> to switch the

112 + branch we're currently on.

113 +

114 +

115 +<pre>

116 +$ ls

117 +README hello.rb

118 +$ echo 'test content' > test.txt

119 +$ echo 'more content' > more.txt

120 +$ git add *.txt

121 +$ git commit -m 'added two files'

122 +[master 8bd6d8b] added two files

123 + 2 files changed, 2 insertions(+), 0 deletions(-)

124 + create mode 100644 more.txt

125 + create mode 100644 test.txt

126 +$ ls

127 +README hello.rb more.txt test.txt

128 +$ git checkout testing

129 +Switched to branch 'testing'

130 +$ ls

131 +README hello.rb

132 +</pre>

133 +

134 + So now we can see that when we switch to the 'testing' branch, our new

135 + files were removed. We could switch back to the 'master' branch and see

136 + them re-appear.

137 +

138 +<pre>

139 +$ ls

140 +README hello.rb

141 +$ git checkout master

142 +Switched to branch 'master'

143 +$ ls

144 +README hello.rb more.txt test.txt

145 +</pre>

146 +

147 + <h4>

148 + git checkout -b (branchname)

149 + create and immediately switch to a branch

150 + </h4>

151 +

152 +

153 + In most cases you will be wanting to switch to the branch immediately, so

154 + you can do work in it and then merging into a branch that only contains

155 + stable work (such as 'master') at a later point when the work in your new

156 + context branch is stable. You can do this pretty easily with

157 + <code>git branch newbranch; git checkout newbranch</code>, but Git gives

158 + you a shortcut for this: <code>git checkout -b newbranch</code>.

159 +

160 +

161 +<pre>

162 +$ git branch

163 +* master

164 +$ ls

165 +README hello.rb more.txt test.txt

166 +$ git checkout -b removals

167 +Switched to a new branch 'removals'

168 +$ git rm more.txt

169 +rm 'more.txt'

170 +$ git rm test.txt

171 +rm 'test.txt'

172 +$ ls

173 +README hello.rb

174 +$ git commit -am 'removed useless files'

175 +[removals 8f7c949] removed useless files

176 + 2 files changed, 0 insertions(+), 2 deletions(-)

177 + delete mode 100644 more.txt

178 + delete mode 100644 test.txt

179 +$ git checkout master

180 +Switched to branch 'master'

181 +$ ls

182 +README hello.rb more.txt test.txt

183 +</pre>

184 +

185 + You can see there how we created a branch, removed some of our files

186 + while in the context of that branch, then switched back to our main branch

187 + and we see the files return. Branching safely isolates work that we do into

188 + contexts we can switch between.

189 +

190 +

191 + If you start on work it is very useful to

192 + always start it in a branch (because it's fast and easy to do) and then

193 + merge it in and delete the branch when you're done. That way if what you're

194 + working on doesn't work out you can easily discard it and if you're forced

195 + to switch back to a more stable context your work in progress is easy to put

196 + aside and then come back to.

197 +

198 + <h4>

199 + git branch -d (branchname)

200 + delete a branch

201 + </h4>

202 +

203 + If we want to delete a branch (such as the 'testing' branch in the

204 + previous example, since there is no unique work on it),

205 + we can run <code>git branch -d (branch)</code> to remove it.

206 +

207 +<pre>

208 +$ git branch

209 +* master

210 + testing

211 +$ git branch -d testing

212 +Deleted branch testing (was 78b2670).

213 +$ git branch

214 +* master

215 +</pre>

216 +

217 +

218 + In a nutshell you use <code>git branch</code> to list your

219 + current branches, create new branches and delete unnecessary or

220 + already merged branches.

221 +

222 +

223 + </div>

224 +</div>

225 +

226 +<div class="box">

227 + <h2>

228 +

229 + <a target="new" href="http://www.kernel.org/pub/software/scm/git/docs/git-merge.html">docs</a>

230 + <a target="new" href="http://progit.org/book/">book</a>

231 +

232 + <a name="merge">git merge</a>

233 + merge a branch context into your current one

234 + </h2>

235 +

236 + <div class="block">

237 + Once you have work isolated in a branch, you will eventually want to

238 + incorporate it into your main branch. You can merge any branch into your

239 + current branch with the <code>git merge</code> command. Let's take as a

240 + simple example the 'removals' branch from above. If we create a branch

241 + and remove files in it and commit our removals to that branch, it is

242 + isolated from our main ('master', in this case) branch. To include those

243 + deletions in your 'master' branch, you can just merge in the 'removals'

244 + branch.

245 +

246 +

247 +<pre>

248 +$ git branch

249 +* master

250 + removals

251 +$ ls

252 +README hello.rb more.txt test.txt

253 +$ git merge removals

254 +Updating 8bd6d8b..8f7c949

255 +Fast-forward

256 + more.txt | 1 -

257 + test.txt | 1 -

258 + 2 files changed, 0 insertions(+), 2 deletions(-)

259 + delete mode 100644 more.txt

260 + delete mode 100644 test.txt

261 +$ ls

262 +README hello.rb

263 +</pre>

264 +

265 + <h4>

266 + more complex merges

267 + </h4>

268 +

269 + Of course, this doesn't just work for simple file additions and

270 + deletions. Git will merge file modifications as well - in fact, it's very

271 + good at it. For example, let's see what happens when we edit a file in

272 + one branch and in another branch we rename it and then edit it and then

273 + merge these branches together. Chaos, you say? Let's see.

274 +

275 +

276 +<pre>

277 +$ git branch

278 +* master

279 +$ cat hello.rb

280 +class HelloWorld

281 + def self.hello

282 + puts "Hello World"

283 + end

284 +end

285 +

286 +HelloWorld.hello

287 +</pre>

288 +

289 + So first we're going to create a new branch named 'change_class' and

290 + switch to it so your class renaming changes are isolated. I'm going to

291 + change each instance of 'HelloWorld' to 'HiWorld'.

292 +

293 +<pre>

294 +$ git checkout -b change_class

295 +M hello.rb

296 +Switched to a new branch 'change_class'

297 +$ vim hello.rb

298 +$ head -1 hello.rb

299 +class HiWorld

300 +$ git commit -am 'changed the class name'

301 +[change_class 3467b0a] changed the class name

302 + 1 files changed, 2 insertions(+), 4 deletions(-)

303 +</pre>

304 +

305 + So now I've committed the class renaming changes to the 'change_class'

306 + branch. If I now switch back to the 'master' branch my class name will

307 + revert to what it was before I switched branches. Here I can change

308 + something different (in this case the printed output) and at the same

309 + time rename the file from <code>hello.rb</code> to <code>ruby.rb</code>.

310 +

311 +

312 +<pre>

313 +$ git checkout master

314 +Switched to branch 'master'

315 +$ git mv hello.rb ruby.rb

316 +$ vim ruby.rb

317 +$ git diff

318 +diff --git a/ruby.rb b/ruby.rb

319 +index 2aabb6e..bf64b17 100644

320 +--- a/ruby.rb

321 ++++ b/ruby.rb

322 +@@ -1,7 +1,7 @@

323 + class HelloWorld

324 +

325 + def self.hello

326 +- puts "Hello World"

327 ++ puts "Hello World from Ruby"

328 + end

329 +

330 + end

331 +$ git commit -am 'added from ruby'

332 +[master b7ae93b] added from ruby

333 + 1 files changed, 1 insertions(+), 1 deletions(-)

334 + rename hello.rb => ruby.rb (65%)

335 +</pre>

336 +

337 + Now those changes are recorded in my 'master' branch. Notice that the

338 + class name is back to 'HelloWorld', not 'HiWorld'. Now I want to

339 + incorporate the 'HiWorld' change so I can just merge in my 'change_class'

340 + branch. However, I've changed the name of the file since I branched,

341 + what will Git do?

342 +

343 +<pre>

344 +$ git branch

345 + change_class

346 +* master

347 +$ git merge change_class

348 +Renaming hello.rb => ruby.rb

349 +Auto-merging ruby.rb

350 +Merge made by recursive.

351 + ruby.rb | 6 ++----

352 + 1 files changed, 2 insertions(+), 4 deletions(-)

353 +$ cat ruby.rb

354 +class HiWorld

355 + def self.hello

356 + puts "Hello World from Ruby"

357 + end

358 +end

359 +

360 +HiWorld.hello

361 +</pre>

362 +

363 + Well, it will just figure it out. Notice that I had no merge conflicts

364 + and the file that had been renamed now has the 'HiWorld' class name change

365 + that was done in the other branch. Pretty cool.

366 +

367 + <h4>

368 + merge conflicts

369 + </h4>

370 +

371 + So, Git merges are magical, we never ever have to deal with merge

372 + conflicts again, right? Not quite. In situations where the same block

373 + of code is edited in different branches there is no way for a computer

374 + to figure it out, so it's up to us. Let's see another example of changing

375 + the same line in two branches.

376 +

377 +

378 +<pre>

379 +$ git branch

380 +* master

381 +$ git checkout -b fix_readme

382 +Switched to a new branch 'fix_readme'

383 +$ vim README

384 +$ git commit -am 'fixed readme title'

385 +[fix_readme 3ac015d] fixed readme title

386 + 1 files changed, 1 insertions(+), 1 deletions(-)

387 +</pre>

388 +

389 + Now we have committed a change to one line in our README file in a

390 + branch. Now let's change the same line in a different way back on

391 + our 'master' branch.

392 +

393 +<pre>

394 +$ git checkout master

395 +Switched to branch 'master'

396 +$ vim README

397 +$ git commit -am 'fixed readme title differently'

398 +[master 3cbb6aa] fixed readme title differently

399 + 1 files changed, 1 insertions(+), 1 deletions(-)

400 +</pre>

401 +

402 + Now is the fun part - we will merge the first branch into our master

403 + branch, causing a merge conflict.

404 +

405 +<pre>

406 +$ git merge fix_readme

407 +Auto-merging README

408 +CONFLICT (content): Merge conflict in README

409 +Automatic merge failed; fix conflicts and then commit the result.

410 +$ cat README

411 +<<<<<<< HEAD

412 +Many Hello World Examples

413 +=======

414 +Hello World Lang Examples

415 +>>>>>>> fix_readme

416 +

417 +This project has examples of hello world in

418 +nearly every programming language.

419 +</pre>

420 +

421 + You can see that Git inserts standard merge conflict markers, much like

422 + Subversion, into files when it gets a merge conflict. Now it's up to us

423 + to resolve them. We will do it manually here, but check out

424 + <a href="http://www.kernel.org/pub/software/scm/git/docs/git-mergetool.html">git mergetool</a>

425 + if you want Git to fire up a graphical mergetool

426 + (like kdiff3, emerge, p4merge, etc) instead.

427 +

428 +

429 +<pre>

430 +$ vim README # here I'm fixing the conflict

431 +$ git diff

432 +diff --cc README

433 +index 9103e27,69cad1a..0000000

434 +--- a/README

435 ++++ b/README

436 +@@@ -1,4 -1,4 +1,4 @@@

437 +- Many Hello World Examples

438 + -Hello World Lang Examples

439 +++Many Hello World Lang Examples

440 +

441 + This project has examples of hello world in

442 +</pre>

443 +

444 + A cool tip in doing merge conflict resolution in Git is that if you

445 + run <code>git diff</code>, it will show you both sides of the conflict

446 + and how you've resolved it as I've shown here. Now it's time to mark

447 + the file as resolved. In Git we do that with <code>git add</code> -

448 + to tell Git the file has been resolved, you have to stage it.

449 +

450 +<pre>

451 +$ git status -s

452 +UU README

453 +$ git add README

454 +$ git status -s

455 +M README

456 +$ git commit

457 +[master 8d585ea] Merge branch 'fix_readme'

458 +</pre>

459 +

460 + And now we've successfully resolved our merge conflict and committed

461 + the result.

462 +

463 + </div>

464 +

465 +</div>

466 +

467 +<a href="/basic">On to Sharing and Updating Projects »</a>

468 +

branch, checkout, merge docs