The Git Workflow: An example based overview

gitWorkflow.md

###Overview This tutorial will provide you with an overview of the recommended Git workflow. We will be using the the HGrid repository to provide a real world example.

####What you'll learn:

1. Forking repositories to your account
2. Cloning freshly forked repos to your machine
3. Adding remotes
4. Adding and deleting branches
5. Merging local branches
6. Pushing changes to a repository
7. Submitting a Pull Request

###Fork the repository

In general it is a bad idea to work directly with the primary repository. Having more than one developer working on the same set of code can get very compicated very quickly.

What we want to do instead is make a copy of the primary repository using your account. This is called forking. The process is quite straightforward

1. Navigate to the primary repository page. For our example this is located here: https://github.com/CenterForOpenScience/HGrid.

2. Click the Fork button in the top right corner.

3. Sit back and watch the pretty forking animation.

Once completed your browser should be redirected to the forked repository underneath your account e.g. https://github.com/hrybacki/HGrid

###Clone the repository

Now that we have forked the repository we need to get a copy of it on your machine.

1. Open up a shell, terminal, or what-have-you and navigate to the directory in which you would like the repository to be placed.

    $ cd /my/repos/go/here
   

2. Clone your repository in the format: git clone https://github.com/"your account"/"name of the repo".git -- for example:

    $ git clone https://github.com/hrybacki/HGrid.git
   
    Cloning into 'HGrid'...
   
    remote: Counting objects: 991, done.
   
    remote: Compressing objects: 100% (378/378), done.
   
    remote: Total 991 (delta 564), reused 984 (delta 558)
   
    Receiving objects: 100% (991/991), 2.52 MiB | 2.55 MiB/s, done.
   
    Resolving deltas: 100% (564/564), done.
   

3. Navigate to your freshly cloned repository.

    $ cd /my/repos/go/here/HGrid
   

###Add a Remote for the Primary Repository

Suppose you are working on this project with Timmy. Before calling it a night yesterday, Timmy finished a bunch of good work and submitted a pull request to CenterForOpenScience/HGrid. That pull request was accepted and merged. But, wait a second ... what about your local copy of the repository? It's behind now, right? Right.

In order to minimize conflicts that can occur from this (and they will occur) it's a good habit to pull from CenterForOpenScience/HGrid (which will will refer to as upstream) to YourUserAccount/HGrid (which we will refer to as origin) before you start working each day.

Some even do it more often!

Before being able to pull from upstream we need to add a remote to our repository.

1. Add a remote to the upstream

    $ git remote add upstream https://github.com/CenterForOpenScience/HGrid
   

2. Verify you have a remote to your fork, origin, and the original repository, upstream)

    $ git remote -v
   

Should look similar to

    origin  https://github.com/hrybacki/HGrid.git (fetch)
    origin  https://github.com/hrybacki/HGrid.git (push)
    upstream	https://github.com/CenterForOpenScience/HGrid (fetch)
    upstream	https://github.com/CenterForOpenScience/HGrid (push)

Note that origin is pointed to hrybacki

and

upstream is pointed to CenterForOpenScience

1. Simulate your good habits by pulling from upstream to your local repository.

    $ git pull upstream master
   

Since you just forked and cloned it everything is likely up to date:

    From https://github.com/CenterForOpenScience/HGrid
     * branch            master     -> FETCH_HEAD
    Already up-to-date.

###Create and Checkout a Branch

When working with a repository on your local machine you need to keep your master branch clean. If you don't, you will increase the probability of merge conflicts when you do your daily pull from upstream.

Ideally, every time you want resolve a bug, add a feature, or resolve an issue you should create a branch for it.

For example, imagine we are going to resolve an issue submitted by a user:

1. Create the branch

    $ git branch issue83
   

2. Verify that the branch was created and list all branches available:

    $ git branch
   
      issue83
    * master
   

Note: The * indicates the branch you are currently working in.

1. Switch to the new branch. In Git lingo we will checkout the branch

    $ git checkout issue83
   

and you're now in issue83!

    Switched to branch 'issue83'

###Get Some Work Done

At this point you are free to fix a bug, implement a feature, resolve an issue, or do whatever it is you needed to do. For example, fictitious issue83 on GitHub requested a file in the root directory that would print someone set us up the bomb when executed.

To resolve this issue I created a new file allYourBase.py in the root directory that prints Someone set us up the bomb when called.

Now, let's add it to git and commit it the issue83 branch we're working in.

1. Add the file to git

    $ git add allYourBase.py 
   

2. Commit the addition

    $ git commit -m "Resolved issue 83. Not sure who wanted this but they are _awesome_"
   

which should output something along the lines of

    [issue83 d395ef1] Resolved issue 83. Not sure who wanted this but they are _awesome_.
     1 file changed, 1 insertion(+)
     create mode 100644 allYourBase.py

###Merge Your Changes, Remove the New Branch, and Push to Origin

Now that we've resolved the issue we need to merge it with our local master branch and push it back to our forked repository origin.

1. Checkout the master branch

    $ git checkout master
   

2. Merge issue83 into the current branch master

    $ git merge issue83
   

you can see allYourBase was added in the output

    Updating 0bcd918..d395ef1
    Fast-forward
     allYourBase.py | 1 +
     1 file changed, 1 insertion(+)
     create mode 100644 allYourBase.py

Now that we've merged the changes into master we no longer need issue83 laying around so let's get rid of it.

1. Delete issue83 branch

    $ git branch -D issue83
   

yields

    Deleted branch issue83 (was d395ef1).

1. Push the changes to forked repository origin

    $ git push origin master
   

note that it is going to your usernames repository

    Counting objects: 43, done.
    Delta compression using up to 4 threads.
    Compressing objects: 100% (25/25), done.
    Writing objects: 100% (28/28), 9.49 KiB, done.
    Total 28 (delta 14), reused 0 (delta 0)
    To https://github.com/hrybacki/HGrid.git
       0879c6c..d395ef1  master -> master

###Submit Your Pull Request

We've accomplished a lot so far. We've managed to fork a repo, clone it, make a custom branch for and resolve an issue on it, merge those changes into our master branch, and finally submit them to our forked repo origin. Now there's only one thing left to do, send our changes to the primary repository. This is the pull request mentioned waaaay back at the start of all this.

1. Navigate to your copy of the repository on GitHub e.g. https://github.com/hrybacki/HGrid

2. Click the Pull Requests button on the top right corner of the page

3. Click the New pull request button toward the top right of the page

4. Review the changes made.

   For example I can see:

    * The commit message 
   
        Resolved issue 83. Not sure who wanted this but they are _awesome_.
   
    * The number of changes made
   
        Resolved issue 83. Not sure who wanted this but they are _awesome_.
   
    * And the line I added in allYourBase.py
   
        +print 'Someone set us up the bomb' 
   

Once you are confident in your changes

1. Click the Click to create a pull request for this comparison button in the middle of the page

2. Fill in your pull request comments and click the Send pull request button on the right side of the page

###Conclusion

And that's all there is. Well, not really. Working with remotes, branches, commits, merges, and pulls has many fine points and there are numerous ways to accomplish similar goals. However, if we all follow a similar work flow we can prevent a lot of very, very bad development nightmares. I hope you've found this useful!