@matheusbsbs / matheus-bagliano / commits / 4c63ff452f
Fork 0

Documentation: git-rebase discussion, miscellaneous user-manual updates

Add discussion of git-rebase, patch series, history rewriting. Mention "pull ." as a synonym for "merge". Remind myself of another case I want to cover in the other-vcs's chapter. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>

J. Bruce Fields committed Jan 7, 2007 at 23:57 UTC 4c63ff452ff04cd13819bf05f30e0df55b50510f
1 file changed +157 -4
Documentation/user-manual.txt
+157 -4
@@ -1090,6 +1090,17 @@ repository that you pulled from.
1090 <<fast-forwards,fast forward>>; instead, your branch will just be
1091 updated to point to the latest commit from the upstream branch).
1092
1093 +The git-pull command can also be given "." as the "remote" repository, in
1094 +which case it just merges in a branch from the current repository; so
1095 +the commands
1096 +
1097 +-------------------------------------------------
1098 +$ git pull . branch
1099 +$ git merge branch
1100 +-------------------------------------------------
1101 +
1102 +are roughly equivalent. The former is actually very commonly used.
1103 +
1104 Submitting patches to a project
1105 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1106
@@ -1418,13 +1429,155 @@ which will display the given version of the file.
1429 Working with other version control systems
1430 ==========================================
1431
1421 -TODO: CVS, Subversion, ?
1432 +TODO: CVS, Subversion, series-of-release-tarballs, ?
1433
1434 [[cleaning-up-history]]
1424 -Cleaning up history: rebasing, cherry-picking, and patch series
1425 -===============================================================
1435 +Rewriting history and maintaining patch series
1436 +==============================================
1437 +
1438 +Normally commits are only added to a project, never taken away or
1439 +replaced. Git is designed with this assumption, and violating it will
1440 +cause git's merge machinery (for example) to do the wrong thing.
1441 +
1442 +However, there is a situation in which it can be useful to violate this
1443 +assumption.
1444 +
1445 +Creating the perfect patch series
1446 +---------------------------------
1447 +
1448 +Suppose you are a contributor to a large project, and you want to add a
1449 +complicated feature, and to present it to the other developers in a way
1450 +that makes it easy for them to read your changes, verify that they are
1451 +correct, and understand why you made each change.
1452 +
1453 +If you present all of your changes as a single patch (or commit), they may
1454 +find it is too much to digest all at once.
1455 +
1456 +If you present them with the entire history of your work, complete with
1457 +mistakes, corrections, and dead ends, they may be overwhelmed.
1458 +
1459 +So the ideal is usually to produce a series of patches such that:
1460 +
1461 + 1. Each patch can be applied in order.
1462 +
1463 + 2. Each patch includes a single logical change, together with a
1464 + message explaining the change.
1465 +
1466 + 3. No patch introduces a regression: after applying any initial
1467 + part of the series, the resulting project still compiles and
1468 + works, and has no bugs that it didn't have before.
1469 +
1470 + 4. The complete series produces the same end result as your own
1471 + (probably much messier!) development process did.
1472 +
1473 +We will introduce some tools that can help you do this, explain how to use
1474 +them, and then explain some of the problems that can arise because you are
1475 +rewriting history.
1476 +
1477 +Keeping a patch series up to date using git-rebase
1478 +--------------------------------------------------
1479 +
1480 +Suppose you have a series of commits in a branch "mywork", which
1481 +originally branched off from "origin".
1482 +
1483 +Suppose you create a branch "mywork" on a remote-tracking branch "origin",
1484 +and created some commits on top of it:
1485 +
1486 +-------------------------------------------------
1487 +$ git checkout -b mywork origin
1488 +$ vi file.txt
1489 +$ git commit
1490 +$ vi otherfile.txt
1491 +$ git commit
1492 +...
1493 +-------------------------------------------------
1494 +
1495 +You have performed no merges into mywork, so it is just a simple linear
1496 +sequence of patches on top of "origin":
1497 +
1498 +
1499 + o--o--o <-- origin
1500 + \
1501 + o--o--o <-- mywork
1502 +
1503 +Some more interesting work has been done in the upstream project, and
1504 +"origin" has advanced:
1505 +
1506 + o--o--O--o--o--o <-- origin
1507 + \
1508 + a--b--c <-- mywork
1509 +
1510 +At this point, you could use "pull" to merge your changes back in;
1511 +the result would create a new merge commit, like this:
1512 +
1513 +
1514 + o--o--O--o--o--o <-- origin
1515 + \ \
1516 + a--b--c--m <-- mywork
1517 +
1518 +However, if you prefer to keep the history in mywork a simple series of
1519 +commits without any merges, you may instead choose to use
1520 +gitlink:git-rebase[1]:
1521 +
1522 +-------------------------------------------------
1523 +$ git checkout mywork
1524 +$ git rebase origin
1525 +-------------------------------------------------
1526 +
1527 +This will remove each of your commits from mywork, temporarily saving them
1528 +as patches (in a directory named ".dotest"), update mywork to point at the
1529 +latest version of origin, then apply each of the saved patches to the new
1530 +mywork. The result will look like:
1531 +
1532 +
1533 + o--o--O--o--o--o <-- origin
1534 + \
1535 + a'--b'--c' <-- mywork
1536 +
1537 +In the process, it may discover conflicts. In that case it will stop and
1538 +allow you to fix the conflicts as described in
1539 +"<<resolving-a-merge,Resolving a merge>>". Once the index is updated with
1540 +the results of the conflict resolution, instead of creating a new commit,
1541 +just run
1542 +
1543 +-------------------------------------------------
1544 +$ git rebase --continue
1545 +-------------------------------------------------
1546 +
1547 +and git will continue applying the rest of the patches.
1548 +
1549 +At any point you may use the --abort option to abort this process and
1550 +return mywork to the state it had before you started the rebase:
1551 +
1552 +-------------------------------------------------
1553 +$ git rebase --abort
1554 +-------------------------------------------------
1555 +
1556 +Reordering or selecting from a patch series
1557 +-------------------------------------------
1558 +
1559 +Given one existing commit, the gitlink:git-cherry-pick[1] command allows
1560 +you to apply the change introduced by that commit and create a new commit
1561 +that records it.
1562 +
1563 +This can be useful for modifying a patch series.
1564 +
1565 +TODO: elaborate
1566 +
1567 +Other tools
1568 +-----------
1569 +
1570 +There are numerous other tools, such as stgit, which exist for the purpose
1571 +of maintianing a patch series. These are out of the scope of this manual.
1572 +
1573 +Problems with rewriting history
1574 +-------------------------------
1575 +
1576 +The primary problem with rewriting the history of a branch has to do with
1577 +merging.
1578 +
1579 +TODO: elaborate
1580
1427 -TODO: rebase, cherry-pick, pointers to other tools (like stgit)
1581
1582 Git internals
1583 =============