@matheusbsbs / matheus-bagliano / commits / 4db75b70d1
Fork 0

Documentation: remove howto's now incorporated into manual

These two howto's have both been copied into the manual. I'd rather not maintain both versions if possible, and I think the user-manual will be more visible than the howto directory. (Though I wouldn't mind some duplication if people really like having them here.) Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>

J. Bruce Fields committed May 12, 2007 at 23:52 UTC 4db75b70d1a4c56bb6d91e03e6f9a84bccb6c760
2 files changed -174
Documentation/howto/dangling-objects.txt deleted
-109
@@ -1,109 +0,0 @@
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 -
Documentation/howto/isolate-bugs-with-bisect.txt deleted
-65
@@ -1,65 +0,0 @@
1 -From: Linus Torvalds <torvalds () osdl ! org>
2 -To: git@vger.kernel.org
3 -Date: 2005-11-08 1:31:34
4 -Subject: Real-life kernel debugging scenario
5 -Abstract: Short-n-sweet, Linus tells us how to leverage `git-bisect` to perform
6 - bug isolation on a repository where "good" and "bad" revisions are known
7 - in order to identify a suspect commit.
8 -
9 -
10 -How To Use git-bisect To Isolate a Bogus Commit
11 -===============================================
12 -
13 -The way to use "git bisect" couldn't be easier.
14 -
15 -Figure out what the oldest bad state you know about is (that's usually the
16 -head of "master", since that's what you just tried to boot and failed at).
17 -Also, figure out the most recent known-good commit (usually the _previous_
18 -kernel you ran: and if you've only done a single "pull" in between, it
19 -will be ORIG_HEAD).
20 -
21 -Then do
22 -
23 - git bisect start
24 - git bisect bad master <- mark "master" as the bad state
25 - git bisect good ORIG_HEAD <- mark ORIG_HEAD as good (or
26 - whatever other known-good
27 - thing you booted last)
28 -
29 -and at this point "git bisect" will churn for a while, and tell you what
30 -the mid-point between those two commits are, and check that state out as
31 -the head of the new "bisect" branch.
32 -
33 -Compile and reboot.
34 -
35 -If it's good, just do
36 -
37 - git bisect good <- mark current head as good
38 -
39 -otherwise, reboot into a good kernel instead, and do (surprise surprise,
40 -git really is very intuitive):
41 -
42 - git bisect bad <- mark current head as bad
43 -
44 -and whatever you do, git will select a new half-way point. Do this for a
45 -while, until git tells you exactly which commit was the first bad commit.
46 -That's your culprit.
47 -
48 -It really works wonderfully well, except for the case where there was
49 -_another_ commit that broke something in between, like introduced some
50 -stupid compile error. In that case you should not mark that commit good or
51 -bad: you should try to find another commit close-by, and do a "git reset
52 ---hard <newcommit>" to try out _that_ commit instead, and then test that
53 -instead (and mark it good or bad).
54 -
55 -You can do "git bisect visualize" while you do all this to see what's
56 -going on by starting up gitk on the bisection range.
57 -
58 -Finally, once you've figured out exactly which commit was bad, you can
59 -then go back to the master branch, and try reverting just that commit:
60 -
61 - git checkout master
62 - git revert <bad-commit-id>
63 -
64 -to verify that the top-of-kernel works with that single commit reverted.
65 -