@matheusbsbs / matheus-bagliano / commits / a9eefb3bfc
Fork 0

Add dangling objects tips.

Signed-off-by: Junio C Hamano <junkio@cox.net>

Linus Torvalds committed Jan 25, 2007 at 21:55 UTC a9eefb3bfc66b7f5dba86ebf57b05e32c33eb9e5
1 file changed +109
Documentation/howto/dangling-objects.txt new
+109
@@ -0,0 +1,109 @@
1 +From: Linus Torvalds <torvalds@linux-foundation.org>
2 +Subject: Re: Question about fsck-objects output
3 +Date: Thu, 25 Jan 2007 12:01:06 -0800 (PST)
4 +Message-ID: <Pine.LNX.4.64.0701251144290.25027@woody.linux-foundation.org>
5 +Archived-At: <http://permalink.gmane.org/gmane.comp.version-control.git/37754>
6 +Abstract: Linus describes what dangling objects are, when they
7 + are left behind, and how to view their relationship with branch
8 + heads in gitk
9 +
10 +On Thu, 25 Jan 2007, Larry Streepy wrote:
11 +
12 +> Sorry to ask such a basic question, but I can't quite decipher the output of
13 +> fsck-objects. When I run it, I get this:
14 +>
15 +> git fsck-objects
16 +> dangling commit 2213f6d4dd39ca8baebd0427723723e63208521b
17 +> dangling commit f0d4e00196bd5ee54463e9ea7a0f0e8303da767f
18 +> dangling blob 6a6d0b01b3e96d49a8f2c7addd4ef8c3bd1f5761
19 +>
20 +>
21 +> Even after a "repack -a -d" they still exist. The man page has a short
22 +> explanation, but, at least for me, it wasn't fully enlightening. :-)
23 +>
24 +> The man page says that dangling commits could be "root" commits, but since my
25 +> repo started as a clone of another repo, I don't see how I could have any root
26 +> commits. Also, the page doesn't really describe what a dangling blob is.
27 +>
28 +> So, can someone explain what these artifacts are and if they are a problem
29 +> that I should be worried about?
30 +
31 +The most common situation is that you've rebased a branch (or you have
32 +pulled from somebody else who rebased a branch, like the "pu" branch in
33 +the git.git archive itself).
34 +
35 +What happens is that the old head of the original branch still exists, as
36 +does obviously everything it pointed to. The branch pointer itself just
37 +doesn't, since you replaced it with another one.
38 +
39 +However, there are certainly other situations too that cause dangling
40 +objects. For example, the "dangling blob" situation you have tends to be
41 +because you did a "git add" of a file, but then, before you actually
42 +committed it and made it part of the bigger picture, you changed something
43 +else in that file and committed that *updated* thing - the old state that
44 +you added originally ends up not being pointed to by any commit/tree, so
45 +it's now a dangling blob object.
46 +
47 +Similarly, when the "recursive" merge strategy runs, and finds that there
48 +are criss-cross merges and thus more than one merge base (which is fairly
49 +unusual, but it does happen), it will generate one temporary midway tree
50 +(or possibly even more, if you had lots of criss-crossing merges and
51 +more than two merge bases) as a temporary internal merge base, and again,
52 +those are real objects, but the end result will not end up pointing to
53 +them, so they end up "dangling" in your repository.
54 +
55 +Generally, dangling objects aren't anything to worry about. They can even
56 +be very useful: if you screw something up, the dangling objects can be how
57 +you recover your old tree (say, you did a rebase, and realized that you
58 +really didn't want to - you can look at what dangling objects you have,
59 +and decide to reset your head to some old dangling state).
60 +
61 +For commits, the most useful thing to do with dangling objects tends to be
62 +to do a simple
63 +
64 + gitk <dangling-commit-sha-goes-here> --not --all
65 +
66 +which means exactly what it sounds like: it says that you want to see the
67 +commit history that is described by the dangling commit(s), but you do NOT
68 +want to see the history that is described by all your branches and tags
69 +(which are the things you normally reach). That basically shows you in a
70 +nice way what the danglign commit was (and notice that it might not be
71 +just one commit: we only report the "tip of the line" as being dangling,
72 +but there might be a whole deep and complex commit history that has gotten
73 +dropped - rebasing will do that).
74 +
75 +For blobs and trees, you can't do the same, but you can examine them. You
76 +can just do
77 +
78 + git show <dangling-blob/tree-sha-goes-here>
79 +
80 +to show what the contents of the blob were (or, for a tree, basically what
81 +the "ls" for that directory was), and that may give you some idea of what
82 +the operation was that left that dangling object.
83 +
84 +Usually, dangling blobs and trees aren't very interesting. They're almost
85 +always the result of either being a half-way mergebase (the blob will
86 +often even have the conflict markers from a merge in it, if you have had
87 +conflicting merges that you fixed up by hand), or simply because you
88 +interrupted a "git fetch" with ^C or something like that, leaving _some_
89 +of the new objects in the object database, but just dangling and useless.
90 +
91 +Anyway, once you are sure that you're not interested in any dangling
92 +state, you can just prune all unreachable objects:
93 +
94 + git prune
95 +
96 +and they'll be gone. But you should only run "git prune" on a quiescent
97 +repository - it's kind of like doing a filesystem fsck recovery: you don't
98 +want to do that while the filesystem is mounted.
99 +
100 +(The same is true of "git-fsck-objects" itself, btw - but since
101 +git-fsck-objects never actually *changes* the repository, it just reports
102 +on what it found, git-fsck-objects itself is never "dangerous" to run.
103 +Running it while somebody is actually changing the repository can cause
104 +confusing and scary messages, but it won't actually do anything bad. In
105 +contrast, running "git prune" while somebody is actively changing the
106 +repository is a *BAD* idea).
107 +
108 + Linus
109 +