user-manual: clean up fast-forward and dangling-objects sections

The previous commit calls attention to the fact that we have two
sections each devoted to fast-forwards and to dangling objects.  Revise
and attempt to differentiate them a bit.  Some more reorganization may
be required later....

Signed-off-by: J. Bruce Fields

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index d353d08c923763d4ab86f2a227585b3900e8a6ce..03206c53442bb0de757eaabc5cd20fd263f5db95 100644 (file)
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1402,12 +1402,11 @@ differently.  Normally, a merge results in a merge commit, with two
 parents, one pointing at each of the two lines of development that
 were merged.
 
 parents, one pointing at each of the two lines of development that
 were merged.
 

-However, if one of the two lines of development is completely
-contained within the other--so every commit present in the one is
-already contained in the other--then git just performs a
-<<fast-forwards,fast forward>>; the head of the current branch is
-moved forward to point at the head of the merged-in branch, without
-any new commits being created.
+However, if the current branch is a descendant of the other--so every
+commit present in the one is already contained in the other--then git
+just performs a "fast forward"; the head of the current branch is moved
+forward to point at the head of the merged-in branch, without any new
+commits being created.

 
 [[fixing-mistakes]]
 Fixing mistakes
 
 [[fixing-mistakes]]
 Fixing mistakes


@@ -1559,8 +1558,10 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
 ...
 -------------------------------------------------
 
 ...
 -------------------------------------------------
 

-Dangling objects are objects that are harmless, but also unnecessary;
-you can remove them at any time with gitlink:git-prune[1] or the --prune
+Dangling objects are not a problem.  At worst they may take up a little
+extra disk space.  They can sometimes provide a last-resort method of
+recovery lost work--see <<dangling-objects>> for details.  However, if
+you want, you may remove them with gitlink:git-prune[1] or the --prune

 option to gitlink:git-gc[1]:
 
 -------------------------------------------------
 option to gitlink:git-gc[1]:
 
 -------------------------------------------------


@@ -1571,9 +1572,6 @@ This may be time-consuming.  Unlike most other git operations (including
 git-gc when run without any options), it is not safe to prune while
 other git operations are in progress in the same repository.
 
 git-gc when run without any options), it is not safe to prune while
 other git operations are in progress in the same repository.
 

-For more about dangling objects, see <<dangling-objects>>.
-
-

 [[recovering-lost-changes]]
 Recovering lost changes
 ~~~~~~~~~~~~~~~~~~~~~~~
 [[recovering-lost-changes]]
 Recovering lost changes
 ~~~~~~~~~~~~~~~~~~~~~~~


@@ -1626,16 +1624,16 @@ 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.
 
 same project, the reflog history is not shared: it tells you only about
 how the branches in your local repository have changed over time.
 

-[[dangling-objects]]
+[[dangling-object-recovery]]

 Examining dangling objects
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 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 contained.  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":
+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
+contained.  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 in the dangling objects that git-fsck reports.  See
+<<dangling-objects>> for the details.

 
 -------------------------------------------------
 $ git fsck
 
 -------------------------------------------------
 $ git fsck


@@ -1667,6 +1665,9 @@ reference pointing to it, for example, a new branch:
 $ git branch recovered-branch 7281251ddd 
 ------------------------------------------------
 
 $ git branch recovered-branch 7281251ddd 
 ------------------------------------------------
 

+Other types of dangling objects (blobs and trees) are also possible, and
+dangling objects can arise in other situations.
+

 
 [[sharing-development]]
 Sharing development with others
 
 [[sharing-development]]
 Sharing development with others


@@ -2260,18 +2261,18 @@ $ git fetch git://example.com/proj.git master:example-master
 will create a new branch named "example-master" and store in it the
 branch named "master" from the repository at the given URL.  If you
 already have a branch named example-master, it will attempt to
 will create a new branch named "example-master" and store in it the
 branch named "master" from the repository at the given URL.  If you
 already have a branch named example-master, it will attempt to

-"fast-forward" to the commit given by example.com's master branch.  So
-next we explain what a fast-forward is:
+<<fast-forwards,fast-forward>> to the commit given by example.com's
+master branch.  In more detail:

 
 

-[[fast-forwards-2]]
-Understanding git history: fast-forwards
-----------------------------------------
+[[fetch-fast-forwards]]
+git fetch and fast-forwards
+---------------------------

 
 In the previous example, when updating an existing branch, "git
 fetch" checks to make sure that the most recent commit on the remote
 branch is a descendant of the most recent commit on your copy of the
 branch before updating your copy of the branch to point at the new
 
 In the previous example, when updating an existing branch, "git
 fetch" checks to make sure that the most recent commit on the remote
 branch is a descendant of the most recent commit on your copy of the
 branch before updating your copy of the branch to point at the new

-commit.  Git calls this process a "fast forward".
+commit.  Git calls this process a <<fast-forwards,fast forward>>.

 
 A fast forward looks something like this:
 
 
 A fast forward looks something like this:
 


@@ -3062,7 +3063,7 @@ objects will work exactly as they did before.
 The gitlink:git-gc[1] command performs packing, pruning, and more for
 you, so is normally the only high-level command you need.
 
 The gitlink:git-gc[1] command performs packing, pruning, and more for
 you, so is normally the only high-level command you need.
 

-[[dangling-objects-2]]
+[[dangling-objects]]

 Dangling objects
 ----------------
 
 Dangling objects
 ----------------
 


@@ -3072,11 +3073,10 @@ objects.  They are not a problem.
 The most common cause of dangling objects is that you've rebased a
 branch, or you have pulled from somebody else who rebased a branch--see
 <<cleaning-up-history>>.  In that case, the old head of the original
 The most common cause of dangling objects is that you've rebased a
 branch, or you have pulled from somebody else who rebased a branch--see
 <<cleaning-up-history>>.  In that case, the old head of the original

-branch still exists, as does obviously everything it pointed to. The
-branch pointer itself just doesn't, since you replaced it with another
-one.
+branch still exists, as does everything it pointed to. The branch
+pointer itself just doesn't, since you replaced it with another one.

 
 

-There are also other situations too that cause dangling objects. For
+There are also other situations that cause dangling objects. For

 example, a "dangling blob" may arise because you did a "git add" of a
 file, but then, before you actually committed it and made it part of the
 bigger picture, you changed something else in that file and committed
 example, a "dangling blob" may arise because you did a "git add" of a
 file, but then, before you actually committed it and made it part of the
 bigger picture, you changed something else in that file and committed


@@ -3098,15 +3098,22 @@ be how 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).
 
 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).
 

-For commits, the most useful thing to do with dangling objects tends to
-be to do a simple
+For commits, you can just use:

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

-For blobs and trees, you can't do the same, but you can examine them.
-You can just do
+This asks for all the history reachable from the given commit but not
+from any branch, tag, or other reference.  If you decide it's something
+you want, you can always create a new reference to it, e.g.,
+
+------------------------------------------------
+$ git branch recovered-branch <dangling-commit-sha-goes-here>
+------------------------------------------------
+
+For blobs and trees, you can't do the same, but you can still examine
+them.  You can just do

 
 ------------------------------------------------
 $ git show <dangling-blob/tree-sha-goes-here>
 
 ------------------------------------------------
 $ git show <dangling-blob/tree-sha-goes-here>