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
=============