This document assumes your GitHub account is: JohnSmith90
                      your email is: John.Smith@me.com
                      you are creating a project called: myproject
                      


Create a GitHub account
=======================
1. Create yourself an account on GitHub:

      www.github.com

Setup
=====
1. Create a public/private key pair:

      cd
      mkdir -p .ssh
      cd .ssh
      ssh-keygen
      cat id_rsa.pub

2. Add the public key to your GitHub account

In GitHub, go to 'Account Settings / SSH Keys' Add the public key
created above (i.e. the contents of id_rsa.pub)

3. Setup your git config

      git config --global user.name "JohnSmith90"
      git config --global user.email "John.Smith@me.com"

(where JohnSmith90 is whatever username you have on GitHub and
grace@me.com is your email address registered with GitHub)

Creating a local git repository
===============================

1. Create a directory for your repository - let's assume you will call it
'myproject'

      mkdir -p ~/git/myproject

2. Initialize git for that repository

      cd ~/git/myproject
      git init

3. Copy in the files that you want to manage e.g. if they are in
~/mycode...

      cp  ~/mycode/*.*  .

4. Add these so that git knows they are to be tracked

      git add *
      git commit -a


Synchronizing your local repository with GitHub
===============================================

1. Create a repository on the github web site

   In the upper-right corner of any page on GitHub, click '+' and then
   click 'New repository'. 

   - IT WILL PROBABLY ASK YOU IF YOU WANT TO CREATE 'IGNORE' FILES AND
   A README.ME - DO *NOT* CREATE ANY FILES IN THAT REPOSITORY VIA THE
   WEB SITE 

4. Specify this as the remote repository. This will be something like

      git remote add origin git@github.com:JohnSmith90/myproject.git

5. Push your local files to the GitHub repository

      git push -u origin master


Changing and adding files
=========================

1. If you change a file, then do

      git commit -a

2. To push the changes to GitHub do

      git push

3. If you add a file, then do

      git add filename

(replacing filename with the name of the file you added)

4. To push the changes to GitHub do

      git commit -a
      git push


To check out your repository on a different machine
===================================================

1. Create a clone of your repository from GitHub

      git clone git@github.com:JohnSmith90/myproject.git

2. Make changes/additions as above and sychronize with GitHub. e.g. 

      git add filename
      git commit -a
      git push

3. To synchronize changes that are on GitHub (that came from machine
A) with a repository that you have cloned (on machine B), on machine B
you would do

      git pull


Creating branches for developing and testing new features
=========================================================

1. create a new branch named "feature_x" and switch to it using

    git checkout -b feature_x

2. switch back to the 'master' branch

    git checkout master

4. Synchronize the branch with GitHub

    git push -u origin feature_x

5. Merge the branch into the main version

    git pull
    git checkout master
    git merge feature_x    
    git commit -a
    git push

6. Delete the branch

    git branch -d feature_x             # This deletes the local branch
    git push origin --delete feature_x  # This deletes the GitHub branch

7. Note - if you pull a branch down on another machine, it may not
   be able to pull down changes back by just doing

   git pull

   In that case do

   git pull origin feature_x
   git push -u origin feature_x


Getting rid of local changes
============================

1. Get rid of changes you have made to a specific file:

      git checkout -- filename

2. Get rid of all changes you have made

      git fetch origin
      git reset --hard origin/master


Tags and releases
=================

1. Create a tag for your current code (e.g. a version number)

      git tag v1.0
      git push --tags

2. Create a release on GitHub (with a ZIP file and a gzipped tar file
for download)

      Visit your repository on GitHub
      Click 'releases'
      Click 'Draft a new release'
      Choose a tag from the dropdown or create a new one
      Fill in the details
      Click 'Publish Release'

3. When creating a new release, it is often useful to be able to
summarize the changes since the last release. You can do this with 

      git log --pretty=format:%s VX.Y..HEAD

where VX.Y is the tag given to your last release. You could also do

      git shortlog VX.Y..HEAD



Reorganizing your repository
============================

This is a bit advanced, but can be very useful! Suppose you have a 
repository with several subdirectories. You want to reorganize things
so that you have one of those subdirectories as a separate repository
of its own (but you want to keep all the history of changes).

First clone the repository in two places. 

To delete everything other than 'subdir', do:

      git filter-branch --subdirectory-filter subdir -- --all 

To delete 'subdir' and keep everything else, do:

      git filter-branch --index-filter 'git rm -r --cached --ignore-unmatched subdir' -- --all

See http://stackoverflow.com/questions/811251/how-can-i-move-a-single-directory-from-a-git-repository-to-a-new-repository-whil

Note that this may not work properly with versions of git prior to 1.7.7.1.