Documentation: getting and installing git
PATCH 1/1 Documentation: getting and installing git
Hi Andrew,
As I promised almost a week ago in the "Hang during rm on ext2 mounted sync (2.6.14-rc2+)" thread, here's a document describing how to obtain and install git.
The document refers people to the git-bisect.txt document in the git source tree for doing bisection searches (no reason to duplicate the info, and if people have git they probably have the source and the document around , or can easily obtain it).
I believe this document matches what you asked for and what I promised to provide.
Please apply or provide comments telling me what should be changed.
---
Documentation/get-and-install-git.txt | 130 ++++++++++++++++++++++++++++++++++ 1 files changed, 130 insertions(+)
Documentation/get-and-install-git.txt new file +130 -0
@@ -0,0 +1,130 @@ + Getting and installing `git` and pulling your first tree + -------------------------------------------------------- + + (Writen by Jesper Juhl, September 2005) + + +This document describes how to obtain and install the `git` tool used (among +other things) to manage the Linux kernel source tree. It also shows you how +to use git to pull down your first copy of the vanilla Linux kernel source +(current git head version). + +The first order of business is to get a copy of git. +You can either obtain the source and compile and install that, or you can use a +binary package for your distribution (if any). +This document will focus on a source install of the latest git snapshot. Binary +packages for some distros can be found at + http://www.kernel.org/pub/software/scm/git/ +Those who already have an older version of git can grab a newer version with + it clone http://www.kernel.org/pub/scm/git/git.git LOCALDIR + +To obtain the latest git source snapshot go to this URL: + http://www.codemonkey.org.uk/projects/git-snapshots/git/ +and download the latest version (at the time of this writing the exact filename +is git-2005-09-29.tar.gz, but a symlink called git-latest.tar.gz is also +provided that will always pull the latest git source regardless of its actual +filename). + +So, now that you have downloaded the file git-2005-09-29.tar.gz (replace with +whatever version you actually downloaded), you need to extract the source +tarball - do the following : + + $ tar zxf git-2005-09-29.tar.gz + +This should leave you with a new directory called "git-snapshot-20050929" +(again, actual name will differ depending on the version you download). +Change into the new directory : + + $ cd git-snapshot-20050929 + +Now it's time to build the source : + + $ make + +This will build a version of git that will install into your own homedir +(~/bin subdir - instructions for building a git that will install globally can +be found in the INSTALL document, but basically it's just "make prefix=/usr"). + +Once the compile finishes it's time to install git : + + $ make install + +(or, if you build a git for global use, su to root first) + +Now git is installed and ready for use. If you build a git for global use +(prefix=/usr), then it should already be in your PATH. If you build git for +just your normal user account (by just typing "make" followed by "make install" +then it may or may not be in your PATH depending on your distribution (not all +distros add ~/bin to the default PATH). If ~/bin is not in your PATH you should +add it (or do a global git install). +Adding ~/bin to your PATH is easy, but slightly distribution (and shell) dependant. +I'll show you a few ways to do it with my distro of choice, Slackware, assuming +you are using the bash shell. + +The first way is to add ~/bin to just your users PATH by adding the following +line to ~/.bash_profile (the personal initialization file, executed for login +shells) : + + export PATH="~/bin:$PATH" + +The second way is adding the same line to ~/.bashrc (the individual +per-interactive-shell startup file). +What file you choose depends on whether you want to make this change only for +login shells. + +The third way is to add ~/bin to the systemwide PATH by adding it to the +existing systemwide PATH set from /etc/profile +The default system PATH set in /etc/profile on a Slackware system looks like +this: + + PATH="/usr/local/bin:/usr/bin:/bin:/usr/X11R6/bin:/usr/games" + +You want to modify that line from /etc/profile to look something like this : + + PATH="~/bin:/usr/local/bin:/usr/bin:/bin:/usr/X11R6/bin:/usr/games" + +Remember to re-login, manually export PATH="~/bin:$PATH" or otherwise update +your current shell environment after making these changes. Do a echo $PATH to +verify that the current effective PATH actually includes ~/bin before +proceeding. + +At this point you should have git installed and available in your PATH. + +Now it's time to download your first kernel source tree. To do that you should +first change into the directory where you want to store the kernel source in a +subdir. I'll assume you want to keep kernel source in ~/linux-kernel, so do +this : + + $ mkdir ~/linux-kernel ; cd ~/linux-kernel + +Now let's use git to download the latest git HEAD (the current head of Linus' +development tree). Execute these commands to do this : + + $ git clone \ + rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git \ + linux-2.6 + $ cd linux-2.6 + $ rsync -a --verbose --stats --progress \ + rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git/ \ + .git/ + +The kernel tree is very large. This constitutes downloading several hundred +megabytes of data, so be patient. +When the download finishes you'll have a brand sparkling new git HEAD linux +kernel source tree in ~/linux-kernel/linux-2.6 + + +Finally, a few links that you may want to visit for more info. + +The main git homepage is at : + http://git.or.cz/ +The Kernel Hackers' Guide to git can be found at : + http://linux.yyz.us/git-howto.html +There's a git manual at : + http://www.kernel.org/pub/software/scm/git/docs/ +A page with links to various descriptions of git use is at : + http://www.kernel.org/pub/software/scm/git/docs/howto-index.html + +If you want to do a git bisection search to find what patch caused a problem, +please see the Documentation/git-bisect.txt document in the git source tree. +You may also want to read and/or use Documentation/git-bisect-script.txt
Hello,
I think Pavel Machek had some short git HOWTO as well, so I'm Cc'ing him.
In general, I think it's not a good idea to just duplicate GIT
documentation in the kernel tree. If you think the GIT documentation is insufficient or is missing some "quick start" document, it'd be more reasonable to submit patches for GIT, but I'd keep kernel's GIT documentation to kernel-specific usage and tips'n'tricks.
Dear diary, on Thu, Sep 29, 2005 at 03:05:01AM CEST, I got a letter where Jesper Juhl <[email protected]> told me that...
Documentation/get-and-install-git.txt line 10
Quoted 13 lines
Documentation/get-and-install-git.txt new file +10
-0@@ -0,0 +1,130 @@ + Getting and installing `git` and pulling your first tree + -------------------------------------------------------- + + (Writen by Jesper Juhl, September 2005) + + +This document describes how to obtain and install the `git` tool used (among +other things) to manage the Linux kernel source tree. It also shows you how +to use git to pull down your first copy of the vanilla Linux kernel source +(current git head version).
Since you're cc'ing me, you'll get a shameless plug. ;-) What about
some decent short notice like:
Note that you might prefer to use one of the simpler user interfaces available for GIT, e.g. the Cogito layer or StGIT patch manager. See the GIT homepage for details.
Documentation/get-and-install-git.txt line 19
Quoted 2 lines
Documentation/get-and-install-git.txt new file +2
-0+Those who already have an older version of git can grab a newer version with + it clone http://www.kernel.org/pub/scm/git/git.git LOCALDIR
Missing leading 'g'.
Documentation/get-and-install-git.txt line 26
Quoted 6 lines
Documentation/get-and-install-git.txt new file +6
-0+To obtain the latest git source snapshot go to this URL: + http://www.codemonkey.org.uk/projects/git-snapshots/git/ +and download the latest version (at the time of this writing the exact filename +is git-2005-09-29.tar.gz, but a symlink called git-latest.tar.gz is also +provided that will always pull the latest git source regardless of its actual +filename).
I think recommending the latest development snapshot instead of the
latest release is a really bad idea if you don't have some really compelling reason to do so. The snapshot can be variously broken and buggy, while a release gives you some stable reference point and path from it you can follow.
...
Documentation/get-and-install-git.txt line 91
Quoted 1 line
Documentation/get-and-install-git.txt new file +1
-0+At this point you should have git installed and available in your PATH.
Perhaps you might rather want to extend GIT's INSTALL file?
Quoted 7 lines
Documentation/get-and-install-git.txt new file +7
-0+Now it's time to download your first kernel source tree. To do that you should +first change into the directory where you want to store the kernel source in a +subdir. I'll assume you want to keep kernel source in ~/linux-kernel, so do +this : + + $ mkdir ~/linux-kernel ; cd ~/linux-kernel +
Documentation/get-and-install-git.txt line 109
Quoted 10 lines
Documentation/get-and-install-git.txt new file +10
-0+Now let's use git to download the latest git HEAD (the current head of Linus' +development tree). Execute these commands to do this : + + $ git clone \ + rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git \ + linux-2.6 + $ cd linux-2.6 + $ rsync -a --verbose --stats --progress \ + rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git/ \ + .git/
Why the second rsync command? If you are after tags and other heads, you can run it just on .git/refs/.
But actually, it is very dangerous. Never ever run it later than right after the initial clone (ignore what the "Kernel Hackers' Guide to git" tells you!). If you did any local commits, it will likely trash them, and if you didn't, it will probably completely confuse the tools which care about updating your working tree with new changes.
Documentation/get-and-install-git.txt line 114
Quoted 2 lines
Documentation/get-and-install-git.txt new file +2
-0+When the download finishes you'll have a brand sparkling new git HEAD linux +kernel source tree in ~/linux-kernel/linux-2.6
[Nitpick] I'm not a native English speaker, but I think "brand new sparkling" is more right.
Documentation/get-and-install-git.txt line 130
Quoted 3 lines
Documentation/get-and-install-git.txt new file +3
-0+If you want to do a git bisection search to find what patch caused a problem, +please see the Documentation/git-bisect.txt document in the git source tree. +You may also want to read and/or use Documentation/git-bisect-script.txt
This notice would be quite useful in the rather antique Documentation/BUG-HUNTING file.
Signature · 4 lines
Petr "Pasky" Baudis Stuff: http://pasky.or.cz/ VI has two modes: the one in which it beeps and the one in which it doesn't.
Quoted 4 lines · Petr Baudis
Hello,
I think Pavel Machek had some short git HOWTO as well, so I'm Cc'ing him.
Ok, thanks. I was not aware of that.
Quoted 6 lines
In general, I think it's not a good idea to just duplicate GIT
documentation in the kernel tree. If you think the GIT documentation is insufficient or is missing some "quick start" document, it'd be more reasonable to submit patches for GIT, but I'd keep kernel's GIT documentation to kernel-specific usage and tips'n'tricks.
The reason for this document is to cater to the people who have a kernel source tree available, know the kernel is managed with git, but don't know how to obtain it. Such people (myself included) probably take a quick look in linux-<version>/Documentation/ for a document telling them how to get and install git. This document is written to serve those people.
Quoted 17 lines
Dear diary, on Thu, Sep 29, 2005 at 03:05:01AM CEST, I got a letter where Jesper Juhl <[email protected]> told me that...
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 line 10
Quoted 13 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +10
-0@@ -0,0 +1,130 @@ + Getting and installing `git` and pulling your first tree + -------------------------------------------------------- + + (Writen by Jesper Juhl, September 2005) + + +This document describes how to obtain and install the `git` tool used (among +other things) to manage the Linux kernel source tree. It also shows you how +to use git to pull down your first copy of the vanilla Linux kernel source +(current git head version).Since you're cc'ing me, you'll get a shameless plug. ;-) What about
I'm Cc'ing you exactely because I thought you would have some valuable input :)
Quoted 6 lines
some decent short notice like:
Note that you might prefer to use one of the simpler user interfaces available for GIT, e.g. the Cogito layer or StGIT patch manager. See the GIT homepage for details.
something like that would probably make sense, yes.
Quoted 5 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 line 12
Quoted 2 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +2
-0+Those who already have an older version of git can grab a newer version with + it clone http://www.kernel.org/pub/scm/git/git.git LOCALDIRMissing leading 'g'.
Whoops.
Quoted 4 lines
Quoted 4 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +4
-0+To obtain the latest git source snapshot go to this URL: + http://www.codemonkey.org.uk/projects/git-snapshots/git/ +and download the latest version (at the time of this writing the exact filename +is git-2005-09-29.tar.gz, but a symlink called git-latest.tar.gz is also
Quoted 9 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 line 18
Quoted 2 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +2
-0+provided that will always pull the latest git source regardless of its actual +filename).I think recommending the latest development snapshot instead of the
latest release is a really bad idea if you don't have some really compelling reason to do so. The snapshot can be variously broken and buggy, while a release gives you some stable reference point and path from it you can follow.
Hmm, yes, you are probably right. I should recommend the latest release and just provide a small note on how to get the latest snapshot. Thanks.
Quoted 5 lines
...
Quoted 1 line
+At this point you should have git installed and available in your PATH.
Perhaps you might rather want to extend GIT's INSTALL file?
I can provide a patch for that if you like, sure.
Quoted 12 lines
Quoted 12 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +12
-0+Now it's time to download your first kernel source tree. To do that you should +first change into the directory where you want to store the kernel source in a +subdir. I'll assume you want to keep kernel source in ~/linux-kernel, so do +this : + + $ mkdir ~/linux-kernel ; cd ~/linux-kernel + +Now let's use git to download the latest git HEAD (the current head of Linus' +development tree). Execute these commands to do this : + + $ git clone \ + rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git \
Quoted 9 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200
Quoted 5 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +5
-0+ linux-2.6 + $ cd linux-2.6 + $ rsync -a --verbose --stats --progress \ + rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git/ \ + .git/Why the second rsync command? If you are after tags and other heads, you can run it just on .git/refs/.
Hmm, right, my bad.
Quoted 2 lines
But actually, it is very dangerous. Never ever run it later than right after the initial clone (ignore what the "Kernel Hackers' Guide to git"
This is supposed to tell people how to get and install git for *the very first time*, so this would be the initial clone.
Quoted 4 lines
tells you!). If you did any local commits, it will likely trash them, and if you didn't, it will probably completely confuse the tools which care about updating your working tree with new changes.
I think the best thing is just to drop that second bit.
Quoted 6 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200
Quoted 2 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +2
-0+When the download finishes you'll have a brand sparkling new git HEAD linux +kernel source tree in ~/linux-kernel/linux-2.6[Nitpick] I'm not a native English speaker, but I think "brand new sparkling" is more right.
I'm not a native english speaker either, so you may very well be right
- I honestly don't know :)
Quoted 7 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200
Quoted 3 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +3
-0+If you want to do a git bisection search to find what patch caused a problem, +please see the Documentation/git-bisect.txt document in the git source tree. +You may also want to read and/or use Documentation/git-bisect-script.txtThis notice would be quite useful in the rather antique
Documentation/BUG-HUNTINGfile.
Not a bad suggestion - anyone else have an oppinion on that?
Thank you for your constructive feedback. Much appreciated.
--
Jesper Juhl <[email protected]>
Don't top-post http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please http://www.expita.com/nomime.html
Just my 2 yen below:
Quoted 125 lines · Jesper Juhl
Quoted 4 lines · Petr Baudis
Hello,
I think Pavel Machek had some short git HOWTO as well, so I'm Cc'ing him.
Ok, thanks. I was not aware of that.
Quoted 6 lines
In general, I think it's not a good idea to just duplicate GIT
documentation in the kernel tree. If you think the GIT documentation is insufficient or is missing some "quick start" document, it'd be more reasonable to submit patches for GIT, but I'd keep kernel's GIT documentation to kernel-specific usage and tips'n'tricks.The reason for this document is to cater to the people who have a kernel source tree available, know the kernel is managed with git, but don't know how to obtain it. Such people (myself included) probably take a quick look in linux-<version>/Documentation/ for a document telling them how to get and install git. This document is written to serve those people.
Quoted 18 lines
Dear diary, on Thu, Sep 29, 2005 at 03:05:01AM CEST, I got a letter where Jesper Juhl <[email protected]> told me that...
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 line 10
Quoted 13 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +10
-0@@ -0,0 +1,130 @@ + Getting and installing `git` and pulling your first tree + -------------------------------------------------------- + + (Writen by Jesper Juhl, September 2005) + + +This document describes how to obtain and install the `git` tool used (among +other things) to manage the Linux kernel source tree. It also shows you how +to use git to pull down your first copy of the vanilla Linux kernel source +(current git head version).Since you're cc'ing me, you'll get a shameless plug. ;-) What about
I'm Cc'ing you exactely because I thought you would have some valuable input :)
Quoted 6 lines
some decent short notice like:
Note that you might prefer to use one of the simpler user interfaces available for GIT, e.g. the Cogito layer or StGIT patch manager. See the GIT homepage for details.
something like that would probably make sense, yes.
Quoted 5 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 line 12
Quoted 2 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +2
-0+Those who already have an older version of git can grab a newer version with + it clone http://www.kernel.org/pub/scm/git/git.git LOCALDIRMissing leading 'g'.
Whoops.
Quoted 4 lines
Quoted 4 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +4
-0+To obtain the latest git source snapshot go to this URL: + http://www.codemonkey.org.uk/projects/git-snapshots/git/ +and download the latest version (at the time of this writing the exact filename +is git-2005-09-29.tar.gz, but a symlink called git-latest.tar.gz is alsoQuoted 9 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 line 18
Quoted 2 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +2
-0+provided that will always pull the latest git source regardless of its actual +filename).I think recommending the latest development snapshot instead of the
latest release is a really bad idea if you don't have some really compelling reason to do so. The snapshot can be variously broken and buggy, while a release gives you some stable reference point and path from it you can follow.Hmm, yes, you are probably right. I should recommend the latest release and just provide a small note on how to get the latest snapshot. Thanks.
Quoted 6 lines
...
Quoted 1 line
+At this point you should have git installed and available in your PATH.
Perhaps you might rather want to extend GIT's INSTALL file?
I can provide a patch for that if you like, sure.
Quoted 12 lines
Quoted 12 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +12
-0+Now it's time to download your first kernel source tree. To do that you should +first change into the directory where you want to store the kernel source in a +subdir. I'll assume you want to keep kernel source in ~/linux-kernel, so do +this : + + $ mkdir ~/linux-kernel ; cd ~/linux-kernel + +Now let's use git to download the latest git HEAD (the current head of Linus' +development tree). Execute these commands to do this : + + $ git clone \ + rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git \Quoted 9 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200
Quoted 5 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +5
-0+ linux-2.6 + $ cd linux-2.6 + $ rsync -a --verbose --stats --progress \ + rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git/ \ + .git/Why the second rsync command? If you are after tags and other heads, you can run it just on .git/refs/.
Quoted 1 line
Hmm, right, my bad.
I am not at all versed ing git, but AFAS rsync is considered, wouldn't it be times faster to start from a tarball (say latest -rc) and then rsync. Most people have it on their machines or it is cached all around the net. Even if they don't have it, getting a tarball to prime the rsync will be a good idea IMHO.
Quoted 38 lines
Quoted 2 lines
But actually, it is very dangerous. Never ever run it later than right after the initial clone (ignore what the "Kernel Hackers' Guide to git"
This is supposed to tell people how to get and install git for *the very first time*, so this would be the initial clone.
Quoted 4 lines
tells you!). If you did any local commits, it will likely trash them, and if you didn't, it will probably completely confuse the tools which care about updating your working tree with new changes.
I think the best thing is just to drop that second bit.
Quoted 6 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200
Quoted 2 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +2
-0+When the download finishes you'll have a brand sparkling new git HEAD linux +kernel source tree in ~/linux-kernel/linux-2.6[Nitpick] I'm not a native English speaker, but I think "brand new sparkling" is more right.
I'm not a native english speaker either, so you may very well be right
- I honestly don't know :)Quoted 7 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200
Quoted 3 lines
Documentation/get-and-install-git.txt 2005-09-29 02:57:59.000000000 +0200 renamed from dev/null 2005-09-28 20:05:57.000000000 +0200 +3
-0+If you want to do a git bisection search to find what patch caused a problem, +please see the Documentation/git-bisect.txt document in the git source tree. +You may also want to read and/or use Documentation/git-bisect-script.txtThis notice would be quite useful in the rather antique
Documentation/BUG-HUNTINGfile.
Quoted 4 lines
Not a bad suggestion - anyone else have an oppinion on that?
Thank you for your constructive feedback. Much appreciated.
Kalin.
Signature · 3 lines
|[ ~~~~~~~~~~~~~~~~~~~~~~ ]| +-> http://ThinRope.net/ <-+ |[ ______________________ ]|