Developing ggplot2 using github

Developing ggplot2 using github

Super-basic setup

If you just want to track the development of ggplot2 and do work on your own local branch, just clone Hadley's repository:

git clone https://github.com/hadley/ggplot2.git

That's it. You don't even have to set up an account on GitHub. Once you've cloned the repo, you can branch, change, and commit. You just won't be able to publish your changes to GitHub. (If you later want to publish these changes to GitHub, it is possible. Ask the mailing list if you need assistance.)

Basic setup

• Set up an account on GitHub and set up ssh keys as described in their instructions.
• Make a fork of Hadley's repository by clicking the Fork button in the upper right. Fore more info, see the GitHub page on forking.)
• Clone your GitHub repository to your local computer (change myname to your account name):

git clone [email protected]:myname/ggplot2.git
cd ggplot2

Once you've done that, you'll probably want to add Hadley's repository as a remote repository

• Add Hadley's repository as a remote repository:

git remote add hadley git://github.com/hadley/ggplot2.git
git fetch hadley

Now on your local machine you have two remote repositories: origin (the default), which is your personal ggplot2 repo at GitHub, and hadley which is Hadley's. You'll be able to push changes to your own repository only.

How to make changes on a new branch

You probably want to start with the master branch from Hadley's repository, although it might be something else, like devel. See the ggplot2 network page to see what the latest is.

# Fetch the latest version of hadley/ggplot2
git fetch hadley

# Check out the latest
git checkout hadley/master

At this point it'll give you a warning about being in "detached HEAD" state. Don't worry about it. Just start a new branch with the current state as the starting point:

git checkout -b myfix

To check what branch you're currently on, run git branch.

Now you can make your changes and commit them to this branch on your local repository. If you decide you want to start over, you can just rename or delete your working branch, check out hadley/master again, and begin anew.

When you feel like sharing your changes, push them to your GitHub repo:

git push origin myfix

Then you can submit a pull request if you want it to be integrated in the main branch.

Testing merges

If your branch has been running parallel to the main branch for a long time, it's possible that it won't merge properly. You can test it out by checking out the main branch and merging yourself.

First, make a new branch called testmerge, based off the main branch:

git fetch hadley
git checkout hadley/master

git checkout -b testmerge

Then try merging your branch into testmerge:

git merge myfix

If there are no errors, great. You can switch back to your myfix branch and delete testmerge:

git checkout myfix
git branch -D testmerge

If there are any merge conflicts, you may want to rebase your changes on top of the current master version, or just resolve the conflicts and commit it to your branch. Rebasing may make for a somewhat cleaner commit history, but there is a possibility of messing things up. If you want to be safe, you can just make a new branch and rebase that on top of the current master.

Visualizing the development tree

GitHub has a very nice development tree view, but it of course only shows commits that have been pushed to GitHub. You may also want to view the tree on your local machine, to see how your local changes relate to the main tree. There are a number of programs out there that will do this.

Mac:

• gitk: Pretty basic, included with git. Run gitk -a to view all branches (by default it just shows you the current branch).
• gitx: This is a bit nicer than gitk.
• SourceTree: This is also a nice program. Normally it costs money, but it is temporarily free from the web page or the Mac App store.

Linux:

• gitk: (See gitk in Mac section)
• gitg: This is nicer than gitk. By default it only shows the current branch; select "Local Branches" or "All Branches" to view others.

Windows:

• ??

Adding other repositories

There are times you may want to try out a branch from someone else's repository. If the person's GitHub account is otherdevel, you would do the following:

git remote add otherdevel git://github.com/otherdevel/ggplot2.git
git fetch otherdevel

git checkout otherdevel/somebranch

If you don't want to follow them any more, run:

git remote rm otherdevel

Tracking a remote branch

You can set up a branch to track hadley/master. This isn't really necessary, but it may be useful in some cases. If you want your master branch to track it, do the following:

git checkout master
git branch --set-upstream master hadley/master

Then run git pull to get it up to date.

Delete a branch from GitHub

If you pushed a branch to GitHub but it's no longer needed there, you can remove it with:

git push origin :mybranch

Set up your shell to show you the current branch

You can view your current branch right at the command prompt, like this:

user@mycomputer:ggplot2 (myfix)$ 

This can help you avoid stupid mistakes. If you're running the bash shell you can add this (as well as tab-completion for git-related stuff):

• Download this script and save it somewhere like ~/git-completion.bash or ~/bin/git-completion.bash.

• In your .bashrc, add the following (note there's an extra space between the \ and [ below, which you must remove. This is because of a weird problem with escape characters on this wiki):

gitmode() {
    source $HOME/bin/git-completion.bash
    PS1="\ [\e]2;\u@\h: \w\a\\]\u@\h:\W\$(__git_ps1)\\$ "
}

Then, in a new terminal window, type gitmode to enable these features.