Update tutorial with Octopus usage.
Making an Octopus is simply a natural extension of merging just one branch into the current branch. Signed-off-by: Junio C Hamano <junkio@cox.net>
Junio C Hamano committed
Sep 20, 2005 at 18:21 UTC
6f60300b5408323f6b73b471b45e539fa49a6a76
1 file changed
+103
-1
Documentation/tutorial.txt
+103
-1
@@ -859,7 +859,12 @@ All of them have plus `+` characters in the first column, which
859
means they are now part of the `master` branch. Only the "Some
860
work" commit has the plus `+` character in the second column,
861
because `mybranch` has not been merged to incorporate these
862
-commits from the master branch.
862
+commits from the master branch. The string inside brackets
863
+before the commit log message is a short name you can use to
864
+name the commit. In the above example, 'master' and 'mybranch'
865
+are branch heads. 'master~1' is the first parent of 'master'
866
+branch head. Please see 'git-rev-parse' documentation if you
867
+see more complex cases.
868
869
Now, let's pretend you are the one who did all the work in
870
`mybranch`, and the fruit of your hard work has finally been merged
@@ -1356,4 +1361,101 @@ fast forward. You need to pull and merge those other changes
1361
back before you push your work when it happens.
1362
1363
1364
+Bundling your work together
1365
+---------------------------
1366
+
1367
+It is likely that you will be working on more than one thing at
1368
+a time. It is easy to use those more-or-less independent tasks
1369
+using branches with git.
1370
+
1371
+We have already seen how branches work in a previous example,
1372
+with "fun and work" example using two branches. The idea is the
1373
+same if there are more than two branches. Let's say you started
1374
+out from "master" head, and have some new code in the "master"
1375
+branch, and two independent fixes in the "commit-fix" and
1376
+"diff-fix" branches:
1377
+
1378
+------------
1379
+$ git show-branch
1380
+! [commit-fix] Fix commit message normalization.
1381
+ ! [diff-fix] Fix rename detection.
1382
+ * [master] Release candidate #1
1383
+---
1384
+ + [diff-fix] Fix rename detection.
1385
+ + [diff-fix~1] Better common substring algorithm.
1386
++ [commit-fix] Fix commit message normalization.
1387
+ + [master] Release candidate #1
1388
++++ [diff-fix~2] Pretty-print messages.
1389
+------------
1390
+
1391
+Both fixes are tested well, and at this point, you want to merge
1392
+in both of them. You could merge in 'diff-fix' first and then
1393
+'commit-fix' next, like this:
1394
+
1395
+------------
1396
+$ git resolve master diff-fix 'Merge fix in diff-fix'
1397
+$ git resolve master commit-fix 'Merge fix in commit-fix'
1398
+------------
1399
+
1400
+Which would result in:
1401
+
1402
+------------
1403
+$ git show-branch
1404
+! [commit-fix] Fix commit message normalization.
1405
+ ! [diff-fix] Fix rename detection.
1406
+ * [master] Merge fix in commit-fix
1407
+---
1408
+ + [master] Merge fix in commit-fix
1409
++ + [commit-fix] Fix commit message normalization.
1410
+ + [master~1] Merge fix in diff-fix
1411
+ ++ [diff-fix] Fix rename detection.
1412
+ ++ [diff-fix~1] Better common substring algorithm.
1413
+ + [master~2] Release candidate #1
1414
++++ [master~3] Pretty-print messages.
1415
+------------
1416
+
1417
+However, there is no particular reason to merge in one branch
1418
+first and the other next, when what you have are a set of truly
1419
+independent changes (if the order mattered, then they are not
1420
+independent by definition). You could instead merge those two
1421
+branches into the current branch at once. First let's undo what
1422
+we just did and start over. We would want to get the master
1423
+branch before these two merges by resetting it to 'master~2':
1424
+
1425
+------------
1426
+$ git reset --hard master~2
1427
+------------
1428
+
1429
+You can make sure 'git show-branch' matches the state before
1430
+those two 'git resolve' you just did. Then, instead of running
1431
+two 'git resolve' commands in a row, you would pull these two
1432
+branch heads (this is known as 'making an Octopus'):
1433
+
1434
+------------
1435
+$ git pull . commit-fix diff-fix
1436
+$ git show-branch
1437
+! [commit-fix] Fix commit message normalization.
1438
+ ! [diff-fix] Fix rename detection.
1439
+ * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
1440
+---
1441
+ + [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
1442
++ + [commit-fix] Fix commit message normalization.
1443
+ ++ [diff-fix] Fix rename detection.
1444
+ ++ [diff-fix~1] Better common substring algorithm.
1445
+ + [master~1] Release candidate #1
1446
++++ [master~2] Pretty-print messages.
1447
+------------
1448
+
1449
+Note that you should not do Octopus because you can. An octopus
1450
+is a valid thing to do and often makes it easier to view the
1451
+commit history if you are pulling more than two independent
1452
+changes at the same time. However, if you have merge conflicts
1453
+with any of the branches you are merging in and need to hand
1454
+resolve, that is an indication that the development happened in
1455
+those branches were not independent after all, and you should
1456
+merge two at a time, documenting how you resolved the conflicts,
1457
+and the reason why you preferred changes made in one side over
1458
+the other. Otherwise it would make the project history harder
1459
+to follow, not easier.
1460
+
1461
[ to be continued.. cvsimports ]