Working with Git and GitHub

This document describes our standard Git development workflow and introduces the basics of how to work with Git and contribute to GitHub hosted projects by way of example. By the end you should be able to download and contribute to GitHub hosted project using the standard pull-request workflow.

Things you'll need

• A GitHub account, sign-up at: https://github.com/signup/free
• Git command-line utility. Follow the instructions at: http://help.github.com/set-up-git-redirect
• Setup Git to rebase on all pulls by issuing the following at the command-line:
  git config --global branch.autosetuprebase always
• Configure auto-correct line endings:
  git config --global core.autocrlf input
• (optional) Configure your favorite text editor as the default for commit messages:
  Windows: http://stackoverflow.com/questions/10564/how-can-i-set-up-an-editor-to-work-with-git-on-windows
  Unix: git config --global core.editor "nano"
• (optional) Configure a tool to handle merges
  http://stackoverflow.com/questions/426026/git-on-windows-how-do-you-set-up-a-mergetool

Workflow Overview

We should first identify the standard Subversion workflow you'll be familiar with so we can contrast it with Git.

1. Checkout a project from the central SVN repository.
2. Make modifications to the project as needed.
3. Update the working copy to ensure the project is up-to-date.
4. Commit the desired changes back to the central server.

This maps most directly to our use of Git and GitHub in the following way:

1. Fork a Project to your GitHub account.
2. Clone your fork of the project to your local machine.
3. Make modifications as needed.
4. Add the changes you want to commit to the “staging area”.
5. Commit the staged changes to your local repository.
6. Pull from the central server to ensure the project is up-to-date
7. Push to your GitHub fork.
8. Create a “pull request” to have your changes “pulled” into the main project.

Contribute to Pentaho-Cookbook

The project you'll contribute to is located on GitHub at:
https://github.com/pentaho-nbaker/pentaho-cookbook

Create your own copy of the Recipe repository

1. Log into GitHub
2. Go to: https://github.com/pentaho-nbaker/pentaho-cookbook
3. Click the “Fork” button. When the process is completed you'll be redirected to your fork of the repository
4. Copy the SSH URL from the horizontal control at top, e.g. git@github.com:...
5. Open a command-line window.
6. Navigate to a directory where you would like to clone your local copy to
7. Execute the following to create a local clone of your fork. When done, you’ll have a full clone of the original repository:
   git clone %URL%
8. By default a special “remote” has been setup which points back to your GitHub fork. You'll also want to create a remote entry for the main repository. CD into your local clone and run:
   git remote add upstream git://github.com/pentaho-nbaker/pentaho-cookbook.git

Make modifications and have them committed back

1. Make some modification to the project, add some CSS, contribute a new recipe, etc.
2. To add a new recipe copy recipes/rhubarb-pie.js into recipes/newRecipe.js and modify.
3. Update index.html to include your new recipe script (just below the existing rhubarb-pie.js reference)
4. Next you need to “add” the modified or new files to the commit staging area:
   git add index.html recipes/newRecipe.js
5. Now commit these staged changes:
   git commit -m "New Recipe and style changes"
6. To get your commit (changeset) incorporated back into the main repository, you need to push it back to GitHub. However, before you do you should "pull" down from the "upstream" remote to ensure you're up-to-date with the latest changes
   git pull upstream master
7. (Optional) You may have to merge your changes with those from the server. Follow instructions here on how to get your “mergetool” setup http://www.gitguys.com/topics/merging-with-a-gui/.
   1. For each conflicted file use the mergetool: git mergetool index.html.
   2. Call git add for each conflicted file which you’ve resolved:
      e.g. git add index.html
   3. Commit the added files to finish the merge operation:
      git commit -m "My merge of foo"
8. Now that you're sure to be up-to-date, push your changes up to your GitHub fork:
   git push
9. Open a browser to your fork of the repository.
10. Click the "Pull Request" button and follow the prompts.
11. Sit back and relax! You’ve made it through.

Helpful Links

Nice Guides:

http://progit.org/book/
http://gitready.com/
http://git-scm.com/documentation

Official Man pages for the commands:
http://www.kernel.org/pub/software/scm/git/docs/v1.7.10/user-manual.html

Lots of Cheat Sheetz:
http://help.github.com/git-cheat-sheets/
http://gitref.org/

Bash command completion:
https://github.com/bobthecow/git-flow-completion/wiki/Install-Bash-git-completion