howto

First steps:
-----------

Strangle the PSU Network Adminstrators

		https://help.github.com/articles/set-up-git/

First off, create an account at github.

And install git.  If they come separately, also install the git manpages.
And git autocomplete comes in handy.

Configure git:

 git config --global user.name "YOUR NAME"
 git config --global user.email "YOUR EMAIL ADDRESS"

Optionally, put a public key into https://github.com/settings/ssh


Fork a repository:
-----------------

		https://help.github.com/articles/fork-a-repo/

Log into github, then browse to

   https://github.com/alijc/git-practice

and click the Fork button.  You'll end up back in your own account.


Clone the repository:
--------------------

Grab the contents of the clone text widget (beside 'HTTPS' or 'SSH') and,
in a terminal, type:

   git clone THAT-TEXT
   cd git-practice


Make changes and update your own repository:
-------------------------------------------

Edit files.  

     # To see what's changed:
     git status

     # To commit them locally:
     git commit ANY-MODIFIED-FILES  
     #(If you created any new files you'll have to "git add" them first.)

     # To push the changes back up to github:
     git push


Using a feature branch:
----------------------

A feature branch is a temporary branch for developing a distinct feature
or bug-fix.  It should exist long enough for development to be finished,
and then be merged into master and deleted.

In the GUI:
   Click on the "Branch: master" button and type in the name of your branch.

   # In your terminal:
   git pull
   git branch -r
   git checkout NEW-BRANCH
   git branch

Or, entirely on the command line:

    git checkout -b NEW-BRANCH
    git push --set-upstream origin NEW-BRANCH


make your changes and commit them locally.
And then push them up, to the feature branch on github.


Merging the feature branch into master:
--------------------------------------

Click the "Compare and pull request" button.  
Write a meaningful comment and click on "Create pull request"
Now you can review the commits and the diffs.
If all looks good, click on the "Merge pull request" button.
And "Confirm" it.
Then "Delete branch".

On the command line:

   git checkout master
   git pull
   git branch -d NEW-BRANCH


Sending a pull request to the original repository:
-------------------------------------------------

First, get all of you changes onto the master branch of your fork.
Then click "New pull request".
Review your changes, and click "Create pull request".
Write a comment and click "Create pull request".

The owner of the original repo receives the pull request and
can 



Working entirely in the browser:
-------------------------------

Somewhere along the way github added the ability to create, edit and commit 
files inside the browser gui. Weird, huh?

You can even browse to someone else's repo and edit one of their files.
github will magically create a branch in your own fork and then let you
send a pull request to the owner.


Syncing a forked repository:
---------------------------

You can't sync a forked repository from the github gui.  
You have to use the command line.

    git remote -v
    # You should only see entries for origin and your own account url

    # Add the original's url as a remote repository:
    git remote add upstream https://github.com/alijc/git-practice.git

    git remote -v
    # You should now see entries for origin and upstream

    # Sync the repos
    git fetch upstream
    git checkout master
    git merge upstream/master
    git push


Collaboration:
-------------

By default, a github repo is created with a single owner, and only that
person has admin or write rights.  But they can set up others to be
collaborators.



Good practices:
--------------

"git status" is your friend.  It will tell you where you are, and give
you a good guess about what you should do next.

Commit often.  If your history gets too long you can always collapse it later.

Push at the end of each coding session.  Or more often.

Pull often, if working on a project with multiple coders, to get their changes.
At the beginning of each session, and before commits.

Likewise, sync your fork before sending a pull request to the original repo.

Agree on a workflow.  
Even if it's just you committing, decide on how you want to do it.