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>

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 11497b7b62c9750410b4686840c85fbe0901a377..be5a1f4c10dfcc7f80da51ac0ab1dcf8523d2e43 100644 (file)
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1412,10 +1412,82 @@ For more about dangling objects, see <<dangling-objects>>.
 Recovering lost changes
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 Recovering lost changes
 ~~~~~~~~~~~~~~~~~~~~~~~
 

-TODO:
-       reflog
-       git-fsck
-       low-level examination of objects
+Reflogs
+^^^^^^^
+
+Say you modify a branch with gitlink:git-reset[1] --hard, and then
+realize that the branch was the only reference you had to that point in
+history.
+
+Fortunately, git also keeps a log, called a "reflog", of all the
+previous values of each branch.  So in this case you can still find the
+old history using, for example, 
+
+-------------------------------------------------
+$ git log master@{1}
+-------------------------------------------------
+
+This lists the commits reachable from the previous version of the head.
+This syntax can be used to with any git command that accepts a commit,
+not just with git log.  Some other examples:
+
+-------------------------------------------------
+$ git show master@{2}          # See where the branch pointed 2,
+$ git show master@{3}          # 3, ... changes ago.
+$ gitk master@{yesterday}      # See where it pointed yesterday,
+$ gitk master@{"1 week ago"}   # ... or last week
+-------------------------------------------------
+
+The reflogs are kept by default for 30 days, after which they may be
+pruned.  See gitlink:git-reflink[1] and gitlink:git-gc[1] to learn
+how to control this pruning, and see the "SPECIFYING REVISIONS"
+section of gitlink:git-rev-parse[1] for details.
+
+Note that the reflog history is very different from normal git history.
+While normal history is shared by every repository that works on the
+same project, the reflog history is not shared: it tells you only about
+how the branches in your local repository have changed over time.
+
+Examining dangling objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In some situations the reflog may not be able to save you.  For
+example, suppose you delete a branch, then realize you need the history
+it pointed you.  The reflog is also deleted; however, if you have not
+yet pruned the repository, then you may still be able to find
+the lost commits; run git-fsck and watch for output that mentions
+"dangling commits":
+
+-------------------------------------------------
+$ git fsck
+dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
+dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
+dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
+...
+-------------------------------------------------
+
+and watch for output that mentions "dangling commits".  You can examine
+one of those dangling commits with, for example,
+
+------------------------------------------------
+$ gitk 7281251ddd --not --all
+------------------------------------------------
+
+which does what it sounds like: it says that you want to see the commit
+history that is described by the dangling commit(s), but not the
+history that is described by all your existing branches and tags.  Thus
+you get exactly the history reachable from that commit that is lost.
+(And notice that it might not be just one commit: we only report the
+"tip of the line" as being dangling, but there might be a whole deep
+and complex commit history that was gotten dropped.)
+
+If you decide you want the history back, you can always create a new
+reference pointing to it, for example, a new branch:
+
+------------------------------------------------
+$ git branch recovered-branch 7281251ddd 
+------------------------------------------------
+

 
 Sharing development with others
 ===============================
 
 Sharing development with others
 ===============================


@@ -2756,22 +2828,13 @@ you recover your old tree (say, you did a rebase, and realized that you
 really didn't want to - you can look at what dangling objects you have, 
 and decide to reset your head to some old dangling state).
 
 really didn't want to - you can look at what dangling objects you have, 
 and decide to reset your head to some old dangling state).
 

-For commits, the most useful thing to do with dangling objects tends to be 
-to do a simple
+For commits, the most useful thing to do with dangling objects tends to
+be to do a simple

 
 ------------------------------------------------
 $ gitk <dangling-commit-sha-goes-here> --not --all
 ------------------------------------------------
 
 
 ------------------------------------------------
 $ gitk <dangling-commit-sha-goes-here> --not --all
 ------------------------------------------------
 

-which means exactly what it sounds like: it says that you want to see the 
-commit history that is described by the dangling commit(s), but you do NOT 
-want to see the history that is described by all your branches and tags 
-(which are the things you normally reach). That basically shows you in a 
-nice way what the dangling commit was (and notice that it might not be 
-just one commit: we only report the "tip of the line" as being dangling, 
-but there might be a whole deep and complex commit history that has gotten 
-dropped - rebasing will do that).
-

 For blobs and trees, you can't do the same, but you can examine them. You 
 can just do
 
 For blobs and trees, you can't do the same, but you can examine them. You 
 can just do