Difference between revisions of "GitHub Guide"

Revision as of 11:30, 3 June 2013

This is a very brief guide of how to quickly get setup for work on the CalVR plugins repository. If you are new to git, there are a bunch of awesome git tutorials out there. Here are some to get you started:

Pro Git

Git Tutorial

Setup

Get an account on GitHub. On your local machine, setup your name and email:

git config --global user.name "Your Name Here"
git config --global user.email "your_email@youremail.com"

Setup ssh keys using this tutorial: Generating SSH Keys Note: Skip the part in Step 4 about installing xclip and instead just copy the contents of ~/.ssh/id_rsa.pub as a single line.

Fork the repository

Once logged in to GitHub, navigate to the CalVR plugins repository and press the Fork button in the upper right. You now have your own copy of the repository to do development work on.

Get the code

To get the code on your local machine, do a clone, replacing "username" with your own username:

 git clone https://github.com/username/calvr_plugins.git

This will create a new directory on your machine containing the code.

For convenience, add the remote repository on GitHub (it can be called whatever you want, but I like origin):

 git remote add origin ssh://github.com/username/calvr_plugins.git

Making changes

Use CalVR_Plugins as a guide for developing a CalVR plugin.

Once you have made changes you would like push up to the GitHub repository, first add the files to be committed.

 git add filename   # add a single file
 git add .          # add the entire contents of your current directory

Commit your changes:

 git commit -m "Descriptive message about the changes being committed."

Pull the most recent code from the remote repository. This will merge your changes with the newest code on GitHub. If there are any conflicts, you will deal with them here. Be sure to have generated and linked your SSH keys to GitHub.

 git pull origin master

Finally push it all up to the remote repository:

 git push origin master

Merging your fork with main calvr_plugins repo

The first time you set this up, you need to add the main calvr_plugins repository as a remote. Do this by running:

git add upstream https://github.com/CalVR/calvr_plugins.git

Then, when you wish to merge in changes from the main calvr_plugins, run these two commands:

git fetch upstream
git merge upstream/master

If there are conflicts, you must fix them manually, then commit.

Pull request

When you have code that is ready to be merged with the main CalVR Plugins repository(it does not break the main build or have any data files committed), initiate a pull request on the GitHub website. Navigate to your forked repository and click the Pull Request button. The base repo should be CalVR/calvr_plugins and the head repo should be username/calvr_plugins. One of the administrators will check your code and merge it into the main repo.