@matheusbsbs / matheus-bagliano / commits / 6f60300b54
Fork 0

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 ]