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>