Here's a guide we put together at the request of a number of users. I have literally lost count on the amount of emails I've received requesting a guide on how to use Github. Well.. I have news for you all; you are not alone - most of us found it confusing at first.  

What is Github?

Github is a place (online) where developers/development teams/companies can store their publicly (or even privately) available source code. Essentially, it is a Version Control System (VCS), which means multiple parties can work on the same development project, and all changes are noted, dated and changes can easily be read at a glance. 

Github is not the only VCS of its kind; there are a number of competitors, in fact. Github just so happens to be the most commonly used VCS in the Android community; with only a very few devevlopers opting for alternate systems. 

---

Setting up Github

Okay, so now you know WHAT it is, you're going to need to know how to set it up (so to speak). For the purposes of this guide, we are using Linux. Github can of course also be used on Windows and OS-X, but you must try and get into the habit of using Linux if you're serious about Android rom development. We're also going to work on the understanding that you have at least a basic understand of linux (how to apt-get, etc). 

So, let's begin.

1. The first thing you'll need to do is download and install git-core, git-gui and git-doc (either via Synaptic), or manually using apt-get (or yum);

sudo apt-get install git-core git-gui git-doc

NOTE : on newer versions of Ubuntu/Debian, you may need to replace git-core with git

2. Next, you'll need to generate SSH keys. To do this, open terminal and type the following commands (in red):

cd ~/.ssh

(To check if you have any existing keys)

If the prompt says "No such file or directory then continue to step 3, otherwise perform these commands;

mkdir key_backup                                     ((makes a directory called key_backup))

cp id_rsa* key_backup                             ((copies the backup to the folder))

rm id_rsa*                                                    ((removes the old key))

3. So it's now time to generate some keys for our use with GitHub. Execute these commands via terminal;

ssh-keygen -t rsa -C "youremail@emailprovider.com"

(Note: I will be using the default settings throughout this guide so when prompted for the directory in which to save the file just press enter)

Enter your passphrase when prompted

4. Now we need to add our SSH keys to GitHub. On the GitHub site, click “Account Settings” > Click “SSH Public Keys” > Click “Add another public key”

Paste your key into the key field and click add key. Now to make sure we've done all that successfully, enter the folowing command into your terminal;

ssh -T git@github.com

If all went well you should get this message:

"The authenticity of host 'github.com (207.97.227.239)' can't be established. RSA key fingerprint is ......

Are you sure you want to continue connecting(yes/no)?"

Type yes and hit enter

If it tells you you've successfully authenticated then you're all done.

Creating a repo

1. Go to your GitHub page and click 'New repository'

2. Give it a project name, description and a homepage URL if you have a website for the project. 

3. Click 'Create Repository'
 

That's it, you've created you're first repo.

1. Now let's push to this repo from our terminal, for now we'll just create a README file which GitHub recommends every repo has. Type the following commands in your terminal;

mkdir ~/First-Project

cd First ~/First-Project

git init

touch README

Now you can edit your README file to include some information about your project, or just leave it be. Whatever you choose won't make a difference to what we're doing, so don't worry too much about it. 

2. Next we need to commit our file. Again, open up your terminal and type:

git add README

git commit -m 'first commit'

git remote add origin git@github.com:username/First-Project.git

git push origin master

Congrats! You've just pushed your first file to GitHub

Forking a repo

Let's say we've seen a nice little project on GitHub that we fancy modifying and helping out with. For this, we use 'fork'.

1. To fork a project, click the fork button on the project repo page. 

2. Once that's finished, your forked project still only exists on GitHub. We need to sync it to our machine and to do this you can execute the following command:

git clone git@github.com:username/Forked-Project.git

3. When a repo is cloned, it has a remote called 'origin', which points to your forked project on GitHub, not the original repo it was forked from. So, to keep track of the original repo and sync it's changes with your own fork, execute the following commands:

cd Forked-Project

git remote add upstream igt://github.com/originalauthor/Original-Project.git

git fetch upstream

4. Once you've made some changes to a forked repo and you want to push it to your forked project, you can use the same commands you would use with a regular repo:

git push origin master

And finally, if you've seen some changes in the original repo you want to add to your forked repo? Use these commands;

git fetch upstream

git merge upstream/master