@matheusbsbs / matheus-bagliano / commits / 597230403b
Fork 0

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

J. Bruce Fields committed Apr 30, 2007 at 11:11 UTC 597230403be52a13b8373222b7604047bacb4bd4
1 file changed +40 -33
Documentation/user-manual.txt
+40 -33
@@ -1402,12 +1402,11 @@ differently. Normally, a merge results in a merge commit, with two
1402 parents, one pointing at each of the two lines of development that
1403 were merged.
1404
1405 -However, if one of the two lines of development is completely
1406 -contained within the other--so every commit present in the one is
1407 -already contained in the other--then git just performs a
1408 -<<fast-forwards,fast forward>>; the head of the current branch is
1409 -moved forward to point at the head of the merged-in branch, without
1410 -any new commits being created.
1405 +However, if the current branch is a descendant of the other--so every
1406 +commit present in the one is already contained in the other--then git
1407 +just performs a "fast forward"; the head of the current branch is moved
1408 +forward to point at the head of the merged-in branch, without any new
1409 +commits being created.
1410
1411 [[fixing-mistakes]]
1412 Fixing mistakes
@@ -1559,8 +1558,10 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
1558 ...
1559 -------------------------------------------------
1560
1562 -Dangling objects are objects that are harmless, but also unnecessary;
1563 -you can remove them at any time with gitlink:git-prune[1] or the --prune
1561 +Dangling objects are not a problem. At worst they may take up a little
1562 +extra disk space. They can sometimes provide a last-resort method of
1563 +recovery lost work--see <<dangling-objects>> for details. However, if
1564 +you want, you may remove them with gitlink:git-prune[1] or the --prune
1565 option to gitlink:git-gc[1]:
1566
1567 -------------------------------------------------
@@ -1571,9 +1572,6 @@ This may be time-consuming. Unlike most other git operations (including
1572 git-gc when run without any options), it is not safe to prune while
1573 other git operations are in progress in the same repository.
1574
1574 -For more about dangling objects, see <<dangling-objects>>.
1575 -
1576 -
1575 [[recovering-lost-changes]]
1576 Recovering lost changes
1577 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -1626,16 +1624,16 @@ While normal history is shared by every repository that works on the
1624 same project, the reflog history is not shared: it tells you only about
1625 how the branches in your local repository have changed over time.
1626
1629 -[[dangling-objects]]
1627 +[[dangling-object-recovery]]
1628 Examining dangling objects
1629 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1630
1633 -In some situations the reflog may not be able to save you. For
1634 -example, suppose you delete a branch, then realize you need the history
1635 -it contained. The reflog is also deleted; however, if you have not
1636 -yet pruned the repository, then you may still be able to find
1637 -the lost commits; run git-fsck and watch for output that mentions
1638 -"dangling commits":
1631 +In some situations the reflog may not be able to save you. For example,
1632 +suppose you delete a branch, then realize you need the history it
1633 +contained. The reflog is also deleted; however, if you have not yet
1634 +pruned the repository, then you may still be able to find the lost
1635 +commits in the dangling objects that git-fsck reports. See
1636 +<<dangling-objects>> for the details.
1637
1638 -------------------------------------------------
1639 $ git fsck
@@ -1667,6 +1665,9 @@ reference pointing to it, for example, a new branch:
1665 $ git branch recovered-branch 7281251ddd
1666 ------------------------------------------------
1667
1668 +Other types of dangling objects (blobs and trees) are also possible, and
1669 +dangling objects can arise in other situations.
1670 +
1671
1672 [[sharing-development]]
1673 Sharing development with others
@@ -2260,18 +2261,18 @@ $ git fetch git://example.com/proj.git master:example-master
2261 will create a new branch named "example-master" and store in it the
2262 branch named "master" from the repository at the given URL. If you
2263 already have a branch named example-master, it will attempt to
2263 -"fast-forward" to the commit given by example.com's master branch. So
2264 -next we explain what a fast-forward is:
2264 +<<fast-forwards,fast-forward>> to the commit given by example.com's
2265 +master branch. In more detail:
2266
2266 -[[fast-forwards-2]]
2267 -Understanding git history: fast-forwards
2268 -----------------------------------------
2267 +[[fetch-fast-forwards]]
2268 +git fetch and fast-forwards
2269 +---------------------------
2270
2271 In the previous example, when updating an existing branch, "git
2272 fetch" checks to make sure that the most recent commit on the remote
2273 branch is a descendant of the most recent commit on your copy of the
2274 branch before updating your copy of the branch to point at the new
2274 -commit. Git calls this process a "fast forward".
2275 +commit. Git calls this process a <<fast-forwards,fast forward>>.
2276
2277 A fast forward looks something like this:
2278
@@ -3062,7 +3063,7 @@ objects will work exactly as they did before.
3063 The gitlink:git-gc[1] command performs packing, pruning, and more for
3064 you, so is normally the only high-level command you need.
3065
3065 -[[dangling-objects-2]]
3066 +[[dangling-objects]]
3067 Dangling objects
3068 ----------------
3069
@@ -3072,11 +3073,10 @@ objects. They are not a problem.
3073 The most common cause of dangling objects is that you've rebased a
3074 branch, or you have pulled from somebody else who rebased a branch--see
3075 <<cleaning-up-history>>. In that case, the old head of the original
3075 -branch still exists, as does obviously everything it pointed to. The
3076 -branch pointer itself just doesn't, since you replaced it with another
3077 -one.
3076 +branch still exists, as does everything it pointed to. The branch
3077 +pointer itself just doesn't, since you replaced it with another one.
3078
3079 -There are also other situations too that cause dangling objects. For
3079 +There are also other situations that cause dangling objects. For
3080 example, a "dangling blob" may arise because you did a "git add" of a
3081 file, but then, before you actually committed it and made it part of the
3082 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
3098 that you really didn't want to - you can look at what dangling objects
3099 you have, and decide to reset your head to some old dangling state).
3100
3101 -For commits, the most useful thing to do with dangling objects tends to
3102 -be to do a simple
3101 +For commits, you can just use:
3102
3103 ------------------------------------------------
3104 $ gitk <dangling-commit-sha-goes-here> --not --all
3105 ------------------------------------------------
3106
3108 -For blobs and trees, you can't do the same, but you can examine them.
3109 -You can just do
3107 +This asks for all the history reachable from the given commit but not
3108 +from any branch, tag, or other reference. If you decide it's something
3109 +you want, you can always create a new reference to it, e.g.,
3110 +
3111 +------------------------------------------------
3112 +$ git branch recovered-branch <dangling-commit-sha-goes-here>
3113 +------------------------------------------------
3114 +
3115 +For blobs and trees, you can't do the same, but you can still examine
3116 +them. You can just do
3117
3118 ------------------------------------------------
3119 $ git show <dangling-blob/tree-sha-goes-here>