user-manual: reflogs, other recovery
Add a brief discussion of reflogs. Also recovery of dangling commits seems to fit in here, so move some of the discussion out of Linus's email to here. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
J. Bruce Fields committed
Jan 29, 2007 at 01:31 UTC
559e4d7a0d2e98e887ac93c78631d3eeef378716
1 file changed
+78
-15
Documentation/user-manual.txt
+78
-15
@@ -1412,10 +1412,82 @@ For more about dangling objects, see <<dangling-objects>>.
1412
Recovering lost changes
1413
~~~~~~~~~~~~~~~~~~~~~~~
1414
1415
-TODO:
1416
- reflog
1417
- git-fsck
1418
- low-level examination of objects
1415
+Reflogs
1416
+^^^^^^^
1417
+
1418
+Say you modify a branch with gitlink:git-reset[1] --hard, and then
1419
+realize that the branch was the only reference you had to that point in
1420
+history.
1421
+
1422
+Fortunately, git also keeps a log, called a "reflog", of all the
1423
+previous values of each branch. So in this case you can still find the
1424
+old history using, for example,
1425
+
1426
+-------------------------------------------------
1427
+$ git log master@{1}
1428
+-------------------------------------------------
1429
+
1430
+This lists the commits reachable from the previous version of the head.
1431
+This syntax can be used to with any git command that accepts a commit,
1432
+not just with git log. Some other examples:
1433
+
1434
+-------------------------------------------------
1435
+$ git show master@{2} # See where the branch pointed 2,
1436
+$ git show master@{3} # 3, ... changes ago.
1437
+$ gitk master@{yesterday} # See where it pointed yesterday,
1438
+$ gitk master@{"1 week ago"} # ... or last week
1439
+-------------------------------------------------
1440
+
1441
+The reflogs are kept by default for 30 days, after which they may be
1442
+pruned. See gitlink:git-reflink[1] and gitlink:git-gc[1] to learn
1443
+how to control this pruning, and see the "SPECIFYING REVISIONS"
1444
+section of gitlink:git-rev-parse[1] for details.
1445
+
1446
+Note that the reflog history is very different from normal git history.
1447
+While normal history is shared by every repository that works on the
1448
+same project, the reflog history is not shared: it tells you only about
1449
+how the branches in your local repository have changed over time.
1450
+
1451
+Examining dangling objects
1452
+^^^^^^^^^^^^^^^^^^^^^^^^^^
1453
+
1454
+In some situations the reflog may not be able to save you. For
1455
+example, suppose you delete a branch, then realize you need the history
1456
+it pointed you. The reflog is also deleted; however, if you have not
1457
+yet pruned the repository, then you may still be able to find
1458
+the lost commits; run git-fsck and watch for output that mentions
1459
+"dangling commits":
1460
+
1461
+-------------------------------------------------
1462
+$ git fsck
1463
+dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
1464
+dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
1465
+dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
1466
+...
1467
+-------------------------------------------------
1468
+
1469
+and watch for output that mentions "dangling commits". You can examine
1470
+one of those dangling commits with, for example,
1471
+
1472
+------------------------------------------------
1473
+$ gitk 7281251ddd --not --all
1474
+------------------------------------------------
1475
+
1476
+which does what it sounds like: it says that you want to see the commit
1477
+history that is described by the dangling commit(s), but not the
1478
+history that is described by all your existing branches and tags. Thus
1479
+you get exactly the history reachable from that commit that is lost.
1480
+(And notice that it might not be just one commit: we only report the
1481
+"tip of the line" as being dangling, but there might be a whole deep
1482
+and complex commit history that was gotten dropped.)
1483
+
1484
+If you decide you want the history back, you can always create a new
1485
+reference pointing to it, for example, a new branch:
1486
+
1487
+------------------------------------------------
1488
+$ git branch recovered-branch 7281251ddd
1489
+------------------------------------------------
1490
+
1491
1492
Sharing development with others
1493
===============================
@@ -2756,22 +2828,13 @@ you recover your old tree (say, you did a rebase, and realized that you
2828
really didn't want to - you can look at what dangling objects you have,
2829
and decide to reset your head to some old dangling state).
2830
2759
-For commits, the most useful thing to do with dangling objects tends to be
2760
-to do a simple
2831
+For commits, the most useful thing to do with dangling objects tends to
2832
+be to do a simple
2833
2834
------------------------------------------------
2835
$ gitk <dangling-commit-sha-goes-here> --not --all
2836
------------------------------------------------
2837
2766
-which means exactly what it sounds like: it says that you want to see the
2767
-commit history that is described by the dangling commit(s), but you do NOT
2768
-want to see the history that is described by all your branches and tags
2769
-(which are the things you normally reach). That basically shows you in a
2770
-nice way what the dangling commit was (and notice that it might not be
2771
-just one commit: we only report the "tip of the line" as being dangling,
2772
-but there might be a whole deep and complex commit history that has gotten
2773
-dropped - rebasing will do that).
2774
-
2838
For blobs and trees, you can't do the same, but you can examine them. You
2839
can just do
2840