@matheusbsbs / matheus-bagliano / commits / 21dcb3b7ab
Fork 0

user-manual: git-fsck, dangling objects

Initial import of fsck and dangling objects discussion, mostly lifted from an email from Linus. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>

J. Bruce Fields committed Jan 28, 2007 at 23:29 UTC 21dcb3b7abfb9e06914a36d1afbc768de6db5f1f
1 file changed +118 -6
Documentation/user-manual.txt
+118 -6
@@ -1373,12 +1373,37 @@ Ensuring reliability
1373 Checking the repository for corruption
1374 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1375
1376 -TODO:
1377 - git-fsck
1378 - "dangling objects" explanation
1379 - Brief explanation here,
1380 - include forward reference to longer explanation from
1381 - Linus, to be added to later chapter
1376 +The gitlink:git-fsck-objects[1] command runs a number of self-consistency
1377 +checks on the repository, and reports on any problems. This may take some
1378 +time. The most common warning by far is about "dangling" objects:
1379 +
1380 +-------------------------------------------------
1381 +$ git fsck-objects
1382 +dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
1383 +dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
1384 +dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
1385 +dangling blob 218761f9d90712d37a9c5e36f406f92202db07eb
1386 +dangling commit bf093535a34a4d35731aa2bd90fe6b176302f14f
1387 +dangling commit 8e4bec7f2ddaa268bef999853c25755452100f8e
1388 +dangling tree d50bb86186bf27b681d25af89d3b5b68382e4085
1389 +dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
1390 +...
1391 +-------------------------------------------------
1392 +
1393 +Dangling objects are objects that are harmless, but also unnecessary; you can
1394 +remove them at any time with gitlink:git-prune[1] or the --prune option to
1395 +gitlink:git-gc[1]:
1396 +
1397 +-------------------------------------------------
1398 +$ git gc --prune
1399 +-------------------------------------------------
1400 +
1401 +This may be time-consuming. Unlike most other git operations (including git-gc
1402 +when run without any options), it is not safe to prune while other git
1403 +operations are in progress in the same repository.
1404 +
1405 +For more about dangling merges, see <<dangling-merges>>.
1406 +
1407
1408 Recovering lost changes
1409 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -2693,6 +2718,93 @@ objects will work exactly as they did before.
2718 The gitlink:git-gc[1] command performs packing, pruning, and more for
2719 you, so is normally the only high-level command you need.
2720
2721 +[[dangling-objects]]
2722 +Dangling objects
2723 +^^^^^^^^^^^^^^^^
2724 +
2725 +The gitlink:git-fsck-objects[1] command will sometimes complain about dangling
2726 +objects. They are not a problem.
2727 +
2728 +The most common cause of dangling objects is that you've rebased a branch, or
2729 +you have pulled from somebody else who rebased a branch--see
2730 +<<cleaning-up-history>>. In that case, the old head of the original branch
2731 +still exists, as does obviously everything it pointed to. The branch pointer
2732 +itself just doesn't, since you replaced it with another one.
2733 +
2734 +There are also other situations too that cause dangling objects. For example, a
2735 +"dangling blob" may arise because you did a "git add" of a file, but then,
2736 +before you actually committed it and made it part of the bigger picture, you
2737 +changed something else in that file and committed that *updated* thing - the
2738 +old state that you added originally ends up not being pointed to by any
2739 +commit or tree, so it's now a dangling blob object.
2740 +
2741 +Similarly, when the "recursive" merge strategy runs, and finds that there
2742 +are criss-cross merges and thus more than one merge base (which is fairly
2743 +unusual, but it does happen), it will generate one temporary midway tree
2744 +(or possibly even more, if you had lots of criss-crossing merges and
2745 +more than two merge bases) as a temporary internal merge base, and again,
2746 +those are real objects, but the end result will not end up pointing to
2747 +them, so they end up "dangling" in your repository.
2748 +
2749 +Generally, dangling objects aren't anything to worry about. They can even
2750 +be very useful: if you screw something up, the dangling objects can be how
2751 +you recover your old tree (say, you did a rebase, and realized that you
2752 +really didn't want to - you can look at what dangling objects you have,
2753 +and decide to reset your head to some old dangling state).
2754 +
2755 +For commits, the most useful thing to do with dangling objects tends to be
2756 +to do a simple
2757 +
2758 +------------------------------------------------
2759 +$ gitk <dangling-commit-sha-goes-here> --not --all
2760 +------------------------------------------------
2761 +
2762 +which means exactly what it sounds like: it says that you want to see the
2763 +commit history that is described by the dangling commit(s), but you do NOT
2764 +want to see the history that is described by all your branches and tags
2765 +(which are the things you normally reach). That basically shows you in a
2766 +nice way what the dangling commit was (and notice that it might not be
2767 +just one commit: we only report the "tip of the line" as being dangling,
2768 +but there might be a whole deep and complex commit history that has gotten
2769 +dropped - rebasing will do that).
2770 +
2771 +For blobs and trees, you can't do the same, but you can examine them. You
2772 +can just do
2773 +
2774 +------------------------------------------------
2775 +$ git show <dangling-blob/tree-sha-goes-here>
2776 +------------------------------------------------
2777 +
2778 +to show what the contents of the blob were (or, for a tree, basically what
2779 +the "ls" for that directory was), and that may give you some idea of what
2780 +the operation was that left that dangling object.
2781 +
2782 +Usually, dangling blobs and trees aren't very interesting. They're almost
2783 +always the result of either being a half-way mergebase (the blob will
2784 +often even have the conflict markers from a merge in it, if you have had
2785 +conflicting merges that you fixed up by hand), or simply because you
2786 +interrupted a "git fetch" with ^C or something like that, leaving _some_
2787 +of the new objects in the object database, but just dangling and useless.
2788 +
2789 +Anyway, once you are sure that you're not interested in any dangling
2790 +state, you can just prune all unreachable objects:
2791 +
2792 +------------------------------------------------
2793 +$ git prune
2794 +------------------------------------------------
2795 +
2796 +and they'll be gone. But you should only run "git prune" on a quiescent
2797 +repository - it's kind of like doing a filesystem fsck recovery: you don't
2798 +want to do that while the filesystem is mounted.
2799 +
2800 +(The same is true of "git-fsck-objects" itself, btw - but since
2801 +git-fsck-objects never actually *changes* the repository, it just reports
2802 +on what it found, git-fsck-objects itself is never "dangerous" to run.
2803 +Running it while somebody is actually changing the repository can cause
2804 +confusing and scary messages, but it won't actually do anything bad. In
2805 +contrast, running "git prune" while somebody is actively changing the
2806 +repository is a *BAD* idea).
2807 +
2808 Glossary of git terms
2809 =====================
2810