diff options
Diffstat (limited to 'Documentation/howto')
| -rw-r--r-- | Documentation/howto/dangling-objects.txt | 109 | ||||
| -rw-r--r-- | Documentation/howto/isolate-bugs-with-bisect.txt | 65 | ||||
| -rw-r--r-- | Documentation/howto/make-dist.txt | 52 | ||||
| -rw-r--r-- | Documentation/howto/using-topic-branches.txt | 296 |
4 files changed, 0 insertions, 522 deletions
diff --git a/Documentation/howto/dangling-objects.txt b/Documentation/howto/dangling-objects.txt deleted file mode 100644 index e82ddae3cf..0000000000 --- a/Documentation/howto/dangling-objects.txt +++ /dev/null @@ -1,109 +0,0 @@ -From: Linus Torvalds <torvalds@linux-foundation.org> -Subject: Re: Question about fsck-objects output -Date: Thu, 25 Jan 2007 12:01:06 -0800 (PST) -Message-ID: <Pine.LNX.4.64.0701251144290.25027@woody.linux-foundation.org> -Archived-At: <http://permalink.gmane.org/gmane.comp.version-control.git/37754> -Abstract: Linus describes what dangling objects are, when they - are left behind, and how to view their relationship with branch - heads in gitk - -On Thu, 25 Jan 2007, Larry Streepy wrote: - -> Sorry to ask such a basic question, but I can't quite decipher the output of -> fsck-objects. When I run it, I get this: -> -> git fsck-objects -> dangling commit 2213f6d4dd39ca8baebd0427723723e63208521b -> dangling commit f0d4e00196bd5ee54463e9ea7a0f0e8303da767f -> dangling blob 6a6d0b01b3e96d49a8f2c7addd4ef8c3bd1f5761 -> -> -> Even after a "repack -a -d" they still exist. The man page has a short -> explanation, but, at least for me, it wasn't fully enlightening. :-) -> -> The man page says that dangling commits could be "root" commits, but since my -> repo started as a clone of another repo, I don't see how I could have any root -> commits. Also, the page doesn't really describe what a dangling blob is. -> -> So, can someone explain what these artifacts are and if they are a problem -> that I should be worried about? - -The most common situation is that you've rebased a branch (or you have -pulled from somebody else who rebased a branch, like the "pu" branch in -the git.git archive itself). - -What happens is that the old head of the original branch still exists, as -does obviously everything it pointed to. The branch pointer itself just -doesn't, since you replaced it with another one. - -However, there are certainly other situations too that cause dangling -objects. For example, the "dangling blob" situation you have tends to be -because you did a "git add" of a file, but then, before you actually -committed it and made it part of the bigger picture, you changed something -else in that file and committed that *updated* thing - the old state that -you added originally ends up not being pointed to by any commit/tree, so -it's now a dangling blob object. - -Similarly, when the "recursive" merge strategy runs, and finds that there -are criss-cross merges and thus more than one merge base (which is fairly -unusual, but it does happen), it will generate one temporary midway tree -(or possibly even more, if you had lots of criss-crossing merges and -more than two merge bases) as a temporary internal merge base, and again, -those are real objects, but the end result will not end up pointing to -them, so they end up "dangling" in your repository. - -Generally, dangling objects aren't anything to worry about. They can even -be very useful: if you screw something up, the dangling objects can be how -you recover your old tree (say, you did a rebase, and realized that you -really didn't want to - you can look at what dangling objects you have, -and decide to reset your head to some old dangling state). - -For commits, the most useful thing to do with dangling objects tends to be -to do a simple - - gitk <dangling-commit-sha-goes-here> --not --all - -which means exactly what it sounds like: it says that you want to see the -commit history that is described by the dangling commit(s), but you do NOT -want to see the history that is described by all your branches and tags -(which are the things you normally reach). That basically shows you in a -nice way what the danglign commit was (and notice that it might not be -just one commit: we only report the "tip of the line" as being dangling, -but there might be a whole deep and complex commit history that has gotten -dropped - rebasing will do that). - -For blobs and trees, you can't do the same, but you can examine them. You -can just do - - git show <dangling-blob/tree-sha-goes-here> - -to show what the contents of the blob were (or, for a tree, basically what -the "ls" for that directory was), and that may give you some idea of what -the operation was that left that dangling object. - -Usually, dangling blobs and trees aren't very interesting. They're almost -always the result of either being a half-way mergebase (the blob will -often even have the conflict markers from a merge in it, if you have had -conflicting merges that you fixed up by hand), or simply because you -interrupted a "git fetch" with ^C or something like that, leaving _some_ -of the new objects in the object database, but just dangling and useless. - -Anyway, once you are sure that you're not interested in any dangling -state, you can just prune all unreachable objects: - - git prune - -and they'll be gone. But you should only run "git prune" on a quiescent -repository - it's kind of like doing a filesystem fsck recovery: you don't -want to do that while the filesystem is mounted. - -(The same is true of "git-fsck-objects" itself, btw - but since -git-fsck-objects never actually *changes* the repository, it just reports -on what it found, git-fsck-objects itself is never "dangerous" to run. -Running it while somebody is actually changing the repository can cause -confusing and scary messages, but it won't actually do anything bad. In -contrast, running "git prune" while somebody is actively changing the -repository is a *BAD* idea). - - Linus - diff --git a/Documentation/howto/isolate-bugs-with-bisect.txt b/Documentation/howto/isolate-bugs-with-bisect.txt deleted file mode 100644 index 926bbdc3cb..0000000000 --- a/Documentation/howto/isolate-bugs-with-bisect.txt +++ /dev/null @@ -1,65 +0,0 @@ -From: Linus Torvalds <torvalds () osdl ! org> -To: git@vger.kernel.org -Date: 2005-11-08 1:31:34 -Subject: Real-life kernel debugging scenario -Abstract: Short-n-sweet, Linus tells us how to leverage `git-bisect` to perform - bug isolation on a repository where "good" and "bad" revisions are known - in order to identify a suspect commit. - - -How To Use git-bisect To Isolate a Bogus Commit -=============================================== - -The way to use "git bisect" couldn't be easier. - -Figure out what the oldest bad state you know about is (that's usually the -head of "master", since that's what you just tried to boot and failed at). -Also, figure out the most recent known-good commit (usually the _previous_ -kernel you ran: and if you've only done a single "pull" in between, it -will be ORIG_HEAD). - -Then do - - git bisect start - git bisect bad master <- mark "master" as the bad state - git bisect good ORIG_HEAD <- mark ORIG_HEAD as good (or - whatever other known-good - thing you booted last) - -and at this point "git bisect" will churn for a while, and tell you what -the mid-point between those two commits are, and check that state out as -the head of the new "bisect" branch. - -Compile and reboot. - -If it's good, just do - - git bisect good <- mark current head as good - -otherwise, reboot into a good kernel instead, and do (surprise surprise, -git really is very intuitive): - - git bisect bad <- mark current head as bad - -and whatever you do, git will select a new half-way point. Do this for a -while, until git tells you exactly which commit was the first bad commit. -That's your culprit. - -It really works wonderfully well, except for the case where there was -_another_ commit that broke something in between, like introduced some -stupid compile error. In that case you should not mark that commit good or -bad: you should try to find another commit close-by, and do a "git reset ---hard <newcommit>" to try out _that_ commit instead, and then test that -instead (and mark it good or bad). - -You can do "git bisect visualize" while you do all this to see what's -going on by starting up gitk on the bisection range. - -Finally, once you've figured out exactly which commit was bad, you can -then go back to the master branch, and try reverting just that commit: - - git checkout master - git revert <bad-commit-id> - -to verify that the top-of-kernel works with that single commit reverted. - diff --git a/Documentation/howto/make-dist.txt b/Documentation/howto/make-dist.txt deleted file mode 100644 index 00e330b293..0000000000 --- a/Documentation/howto/make-dist.txt +++ /dev/null @@ -1,52 +0,0 @@ -Date: Fri, 12 Aug 2005 22:39:48 -0700 (PDT) -From: Linus Torvalds <torvalds@osdl.org> -To: Dave Jones <davej@redhat.com> -cc: git@vger.kernel.org -Subject: Re: Fwd: Re: git checkout -f branch doesn't remove extra files -Abstract: In this article, Linus talks about building a tarball, - incremental patch, and ChangeLog, given a base release and two - rc releases, following the convention of giving the patch from - the base release and the latest rc, with ChangeLog between the - last rc and the latest rc. - -On Sat, 13 Aug 2005, Dave Jones wrote: -> -> > Git actually has a _lot_ of nifty tools. I didn't realize that people -> > didn't know about such basic stuff as "git-tar-tree" and "git-ls-files". -> -> Maybe its because things are moving so fast :) Or maybe I just wasn't -> paying attention on that day. (I even read the git changes via RSS, -> so I should have no excuse). - -Well, git-tar-tree has been there since late April - it's actually one of -those really early commands. I'm pretty sure the RSS feed came later ;) - -I use it all the time in doing releases, it's a lot faster than creating a -tar tree by reading the filesystem (even if you don't have to check things -out). A hidden pearl. - -This is my crappy "release-script": - - [torvalds@g5 ~]$ cat bin/release-script - #!/bin/sh - stable="$1" - last="$2" - new="$3" - echo "# git-tag v$new" - echo "git-tar-tree v$new linux-$new | gzip -9 > ../linux-$new.tar.gz" - echo "git-diff-tree -p v$stable v$new | gzip -9 > ../patch-$new.gz" - echo "git-rev-list --pretty v$new ^v$last > ../ChangeLog-$new" - echo "git-rev-list --pretty=short v$new ^v$last | git-shortlog > ../ShortLog" - echo "git-diff-tree -p v$last v$new | git-apply --stat > ../diffstat-$new" - -and when I want to do a new kernel release I literally first tag it, and -then do - - release-script 2.6.12 2.6.13-rc6 2.6.13-rc7 - -and check that things look sane, and then just cut-and-paste the commands. - -Yeah, it's stupid. - - Linus - diff --git a/Documentation/howto/using-topic-branches.txt b/Documentation/howto/using-topic-branches.txt deleted file mode 100644 index 2c98194cb8..0000000000 --- a/Documentation/howto/using-topic-branches.txt +++ /dev/null @@ -1,296 +0,0 @@ -Date: Mon, 15 Aug 2005 12:17:41 -0700 -From: tony.luck@intel.com -Subject: Some tutorial text (was git/cogito workshop/bof at linuxconf au?) -Abstract: In this article, Tony Luck discusses how he uses GIT - as a Linux subsystem maintainer. - -Here's something that I've been putting together on how I'm using -GIT as a Linux subsystem maintainer. - --Tony - -Last updated w.r.t. GIT 1.1 - -Linux subsystem maintenance using GIT -------------------------------------- - -My requirements here are to be able to create two public trees: - -1) A "test" tree into which patches are initially placed so that they -can get some exposure when integrated with other ongoing development. -This tree is available to Andrew for pulling into -mm whenever he wants. - -2) A "release" tree into which tested patches are moved for final -sanity checking, and as a vehicle to send them upstream to Linus -(by sending him a "please pull" request.) - -Note that the period of time that each patch spends in the "test" tree -is dependent on the complexity of the change. Since GIT does not support -cherry picking, it is not practical to simply apply all patches to the -test tree and then pull to the release tree as that would leave trivial -patches blocked in the test tree waiting for complex changes to accumulate -enough test time to graduate. - -Back in the BitKeeper days I achieved this by creating small forests of -temporary trees, one tree for each logical grouping of patches, and then -pulling changes from these trees first to the test tree, and then to the -release tree. At first I replicated this in GIT, but then I realised -that I could so this far more efficiently using branches inside a single -GIT repository. - -So here is the step-by-step guide how this all works for me. - -First create your work tree by cloning Linus's public tree: - - $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work - -Change directory into the cloned tree you just created - - $ cd work - -Set up a remotes file so that you can fetch the latest from Linus' master -branch into a local branch named "linus": - - $ cat > .git/remotes/linus - URL: git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git - Pull: master:linus - ^D - -and create the linus branch: - - $ git branch linus - -The "linus" branch will be used to track the upstream kernel. To update it, -you simply run: - - $ git fetch linus - -you can do this frequently (and it should be safe to do so with pending -work in your tree, but perhaps not if you are in mid-merge). - -If you need to keep track of other public trees, you can add remote branches -for them too: - - $ git branch another - $ cat > .git/remotes/another - URL: ... insert URL here ... - Pull: name-of-branch-in-this-remote-tree:another - ^D - -and run: - - $ git fetch another - -Now create the branches in which you are going to work, these start -out at the current tip of the linus branch. - - $ git branch test linus - $ git branch release linus - -These can be easily kept up to date by merging from the "linus" branch: - - $ git checkout test && git merge "Auto-update from upstream" test linus - $ git checkout release && git merge "Auto-update from upstream" release linus - -Important note! If you have any local changes in these branches, then -this merge will create a commit object in the history (with no local -changes git will simply do a "Fast forward" merge). Many people dislike -the "noise" that this creates in the Linux history, so you should avoid -doing this capriciously in the "release" branch, as these noisy commits -will become part of the permanent history when you ask Linus to pull -from the release branch. - -Set up so that you can push upstream to your public tree (you need to -log-in to the remote system and create an empty tree there before the -first push). - - $ cat > .git/remotes/mytree - URL: master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git - Push: release - Push: test - ^D - -and the push both the test and release trees using: - - $ git push mytree - -or push just one of the test and release branches using: - - $ git push mytree test -or - $ git push mytree release - -Now to apply some patches from the community. Think of a short -snappy name for a branch to hold this patch (or related group of -patches), and create a new branch from the current tip of the -linus branch: - - $ git checkout -b speed-up-spinlocks linus - -Now you apply the patch(es), run some tests, and commit the change(s). If -the patch is a multi-part series, then you should apply each as a separate -commit to this branch. - - $ ... patch ... test ... commit [ ... patch ... test ... commit ]* - -When you are happy with the state of this change, you can pull it into the -"test" branch in preparation to make it public: - - $ git checkout test && git merge "Pull speed-up-spinlock changes" test speed-up-spinlocks - -It is unlikely that you would have any conflicts here ... but you might if you -spent a while on this step and had also pulled new versions from upstream. - -Some time later when enough time has passed and testing done, you can pull the -same branch into the "release" tree ready to go upstream. This is where you -see the value of keeping each patch (or patch series) in its own branch. It -means that the patches can be moved into the "release" tree in any order. - - $ git checkout release && git merge "Pull speed-up-spinlock changes" release speed-up-spinlocks - -After a while, you will have a number of branches, and despite the -well chosen names you picked for each of them, you may forget what -they are for, or what status they are in. To get a reminder of what -changes are in a specific branch, use: - - $ git-whatchanged branchname ^linus | git-shortlog - -To see whether it has already been merged into the test or release branches -use: - - $ git-rev-list branchname ^test -or - $ git-rev-list branchname ^release - -[If this branch has not yet been merged you will see a set of SHA1 values -for the commits, if it has been merged, then there will be no output] - -Once a patch completes the great cycle (moving from test to release, then -pulled by Linus, and finally coming back into your local "linus" branch) -the branch for this change is no longer needed. You detect this when the -output from: - - $ git-rev-list branchname ^linus - -is empty. At this point the branch can be deleted: - - $ git branch -d branchname - -Some changes are so trivial that it is not necessary to create a separate -branch and then merge into each of the test and release branches. For -these changes, just apply directly to the "release" branch, and then -merge that into the "test" branch. - -To create diffstat and shortlog summaries of changes to include in a "please -pull" request to Linus you can use: - - $ git-whatchanged -p release ^linus | diffstat -p1 -and - $ git-whatchanged release ^linus | git-shortlog - - -Here are some of the scripts that I use to simplify all this even further. - -==== update script ==== -# Update a branch in my GIT tree. If the branch to be updated -# is "linus", then pull from kernel.org. Otherwise merge local -# linus branch into test|release branch - -case "$1" in -test|release) - git checkout $1 && git merge "Auto-update from upstream" $1 linus - ;; -linus) - before=$(cat .git/refs/heads/linus) - git fetch linus - after=$(cat .git/refs/heads/linus) - if [ $before != $after ] - then - git-whatchanged $after ^$before | git-shortlog - fi - ;; -*) - echo "Usage: $0 linus|test|release" 1>&2 - exit 1 - ;; -esac - -==== merge script ==== -# Merge a branch into either the test or release branch - -pname=$0 - -usage() -{ - echo "Usage: $pname branch test|release" 1>&2 - exit 1 -} - -if [ ! -f .git/refs/heads/"$1" ] -then - echo "Can't see branch <$1>" 1>&2 - usage -fi - -case "$2" in -test|release) - if [ $(git-rev-list $1 ^$2 | wc -c) -eq 0 ] - then - echo $1 already merged into $2 1>&2 - exit 1 - fi - git checkout $2 && git merge "Pull $1 into $2 branch" $2 $1 - ;; -*) - usage - ;; -esac - -==== status script ==== -# report on status of my ia64 GIT tree - -gb=$(tput setab 2) -rb=$(tput setab 1) -restore=$(tput setab 9) - -if [ `git-rev-list release ^test | wc -c` -gt 0 ] -then - echo $rb Warning: commits in release that are not in test $restore - git-whatchanged release ^test -fi - -for branch in `ls .git/refs/heads` -do - if [ $branch = linus -o $branch = test -o $branch = release ] - then - continue - fi - - echo -n $gb ======= $branch ====== $restore " " - status= - for ref in test release linus - do - if [ `git-rev-list $branch ^$ref | wc -c` -gt 0 ] - then - status=$status${ref:0:1} - fi - done - case $status in - trl) - echo $rb Need to pull into test $restore - ;; - rl) - echo "In test" - ;; - l) - echo "Waiting for linus" - ;; - "") - echo $rb All done $restore - ;; - *) - echo $rb "<$status>" $restore - ;; - esac - git-whatchanged $branch ^linus | git-shortlog -done |