[AT&T Samsung Galaxy Note II] garyd9:
Before reading this page, I want to point out that I'm fairly weak on git and github. I might be giving instructions that use the incorrect phrasing or are just simply the wrong way of doing things. If you see me doing this and you know better, PLEASE post a message on the companion discussion thread. If there's a better way, I want to know about it, and I want to update this post to reflect it. Keep in mind, though, that I'm trying to simplify things here for the HOWTO, so if your suggestion is more complex (or would require me to type two pages to explain it) I might not update this post with it.​

Most linux-based kernel development these days uses a form of version control (source control, revision control, etc) that will catalog each change made to the source as a change set (or a commit.) Of these, "git" is the most prevalent. Git was written from the ground up specifically for linux development (by the folks who originally created linux) and to meet the very distributed needs of linux kernel development. For more information on git, wikipedia has a good article: http://en.wikipedia.org/wiki/Git_(software)

Along with "git" as the version control system, we'll be using Github as a free hosting service for out git repositories. Github acts like a server for projects using git for revision control. While the site is somewhat geared as a "social" code sharing website, you don't have to be a friendly person to use it. (They even let me use it!) In fact, it's perfectly acceptable to use Github as a server for a project that only you are working on. It's extremely well suited to act as a remote backup for your code projects (which, I admit, I abuse it as) and it serves one other purpose for us: It's an extremely easy way to meet the legal requirement that our linux source is freely available.

Git (and Github) offers a really nice mechanism for a person (such as a reader of this thread) to start a new git project based on the source code of someone else (such as an original kernel project I'll set up for that purpose.) In git's terms, you will "fork" my project into something that belongs to you. Internally, you're only actually creating a link in your project to a very specific version of mine, but it appears and acts like a full copy. (In ways, it's actually BETTER than a normal copy.)

You can, of course, also create a new project from scratch and add new files directly. However, it's considered a better practice to fork from an existing project if possible. This saves a considerable amount of space on the Github server as it's really only keeping a single copy of that original source. It also makes it much easier to pull in changes from the original project (and push changes back to it.) Unfortunately, it's sometimes difficult to find a "clean" branch to fork from. For the purpose of this HOWTO, I've created a clean copy of the SGH-i317 sources in a project in Github and you'll be able to fork from that.

Before forking my project, you'll first need to create a Github account if you don't already have one. Just go to http://github.com and click "Sign up for free." You'll be presented with a page reminding you of the high cost of this service (free) and asking you for a username, email address, and password. Fill in that information and click "Create an account" (which implies acceptance of their terms of service and privacy policy.) That's it. You now have a Github account.

While logged in with your Github account, you want to find a project to fork from. As mentioned, I have a pristine copy of Samsung's actual source release for the i317 set up for just this purpose. Up at the top of the Github webpage, you can search for that project. Just type "linux_kernel_sgh-i317" into that search bar, and you should get a result pointing to "garyd9/linux_kernel_sgh-i317." If you click that link, you'll end up at "https://github.com/garyd9/linux_kernel_sgh-i317"

Finally, you'll go ahead and fork a copy of that for your own use. This is a highly complicated procedure so please pay very careful attention to these instructions: On the upper left of the Github webpage, there's a button labeled "Fork." Go ahead and press it. That's it. (Some people actually mess this up. I have no idea how.) You now have, at least on the github site, your own copy of the kernel source. Leave that browser window open while doing the next step. It contains something we'll need very shortly...

(Parts of this are taken from Github's own "Bootcamp/Set Up Git" webpage at: https://help.github.com/articles/set-up-git#platform-linux I'd encourage you to go to that link and review it as well.)

Back on your build machine, open up a 'terminal' window and type the following command, replacing "Your Name" with your own name. Leave the quotation marks in place.

git config --global user.name "Your Name"

This is telling your local git software what your name is. This shows up in all your git commits, so you probably don't want to put something stupid here.

Also in the terminal window, you'll type this next command. This time, replace "your@email.com" with the email address you used to register on Github. (This is important!)

git config --global user.email your@email.com

Finally, there is one more command to type. This last one will tell git to cache (store) your Github account information so you don't have to type a password every single time you push to the server. (By default, it caches for 15 minutes. Read the Github bootcamp article linked above to find out how to extend that.)

git config --global credential.helper cache

Before we tell git to actually pull the source code from Github, there's one more little organizational thing I like to do. I like to keep all files related to building of a kernel in a single directory on my linux machine. There's more than just a kernel required for building the kernel! So, go ahead and copy the following commands to your terminal window:

cd
mkdir kernel-howto
cd kernel-howto

Now, everything related to this HOWTO can be put into one place: That newly created "kernel-howto" directory that we also changed into.

Now, it's finally time to get the source code to your build machine. Remember I suggested leaving the browser window open on the github page showing your newly forked project? Well, what we actually want is the page URL. It should look something like "https://github.com/yourUserName/linux_kernel-i317" "yourUserName" should be your Github username. We need that URL and add ".git" to tell git what to fetch. In this case, we'll be using the "clone" command which basically just tells git to make a copy of the remote project. You won't be able to just copy/paste the following command into your terminal window, because you'll have to change at least the yourUserName part of the URL. Go ahead and type this command (making the change needed.)

git clone https://github.com/yourUserName/linux_kernel_sgh-i317.git

When the command finishes, you'll have a new sub-directory inside of "kernel-howto" that's called "linux_kernel_sgh-i317". Go ahead and change into this directory.

cd linux_kernel_sgh-i317

There's only one last thing I want to do here before ending this post, and that's to ensure anyone following this HOWTO is able to push changes. To do this, just copy the following commands that will create an empty (and meaningless) file, add it to git, commit it as a change, and push it to the server.

touch HOWTO
git add -A
git commit -m "test commit"
git push

After the "git push" command is sent, you should be prompted for your github username and password. After you enter that information, you should see something similar to the following (the characters before "master->master" will be different):

To https://github.com/yourUserName/linux_kernel_sgh-i317.git
e3d49d2..ea9fbe9 master -> master

You can also go back to your Github page for this project to see the commit on Github. If you aren't on that page anymore, log in to Github, and click the linux_kernel_sgh-i317 repository on the right side of the webpage. Then find and click the "Commits" link (which is between "Files" and "Branches" a few lines down from the top of the page.) The top commit will be the "test commit" that you did on your build machine and pushed to Github.

The kernel isn't quite ready to be compiled. We'll get to that in the next post. In the meantime, if you'd like to learn more about using git and github, there's an interesting interactive walk-through style tutorial at http://try.github.com.