CS169 Setup Guide - Ruby, RubyGems, Git, GitHub

Summary

By the end of this setup, you should:

1. Be able to require ‘rubygems’ from a Ruby script file

2. Have emailed the course staff your GitHub user account name for the semester

3. Been able to push code to a private Git repository on GitHub.

PART 1: Ruby, RubyGems, Git

If you’re on Windows, check out the Windows Setup guide for part 1.

Ruby is the scripting language that we will be using for this class.

RubyGems is a package management system for Ruby libraries, which are in a format called a gem.

Git is a distributed version control system, which serves a similar purpose to Subversion but operates in a very different manner.

Installing Ruby

You will need a version of Ruby >= 1.8.6 but < 1.9.

OS X

If you have Snow Leopard or Leopard, an appropriate version of Ruby should be installed already:

bdon:~ Bdon$ ruby --version

ruby 1.8.7 (2009-06-12 patchlevel 174) [universal-darwin10.0]

Linux

On Linux, you should install Ruby 1.8 through your package manager.

In Debian/Ubuntu:

1. Install tools necessary to build:

        
sudo apt-get install build-essentials

2. Install Ruby

        sudo apt-get install ruby ri rdoc irb ruby-dev libruby

libreadline-ruby libopenssl-ruby

If your package manager suggests other packages are recommended, go ahead and install those as well.

Double-check that you have the right version

ruby -v

It should indicate that you have version 1.8.7.

Using Ruby

Once you have Ruby installed, you can start an interactive session with the irb command.

You can evaluate a script with ruby <script>.rb . Try it out:

bdon:~ Bdon$ irb

>> puts 'hello Ruby!'

hello Ruby!

=> nil

>>

Installing RubyGems

OS X Users can get a RubyGems binary at http://rubygems.org/.

Linux users:

Install RubyGems

        
sudo apt-get install rubygems

Double-check that you have the right version
        gem -v

It should indicate that you have version 1.3.7. If you have an older version, do the following:
        sudo gem install rubygems-update

cd /var/lib/gems/1.8/bin/

sudo ./update_rubygems

IMPORTANT NOTE FOR LINUX USERS: While some gems are available through your distribution’s package manager, you should instead install all gems through rubygems. This will ensure that the most up-to-date gems are available.

Using RubyGems

bdon:~ Bdon$ irb

>> require 'rubygems'

If that doesn’t throw an exception, you have RubyGems installed correctly.

Now you can install a library:

IMPORTANT NOTE FOR OS X AND LINUX USERS: Always use sudo when installing gems. This ensures that anything the gem needs to add to your PATH succeeds.

bdon:~ Bdon$ sudo gem install hpricot

Password:

Building native extensions.  This could take a while...

Successfully installed hpricot-0.8.2

1 gem installed

Installing ri documentation for hpricot-0.8.2...

Installing RDoc documentation for hpricot-0.8.2...

bdon:~ Bdon$

And in an irb session or script you should now be able to:

require ‘rubygems’

require ‘hpricot’

Installing Git

Windows and Mac: git-scm.org has binaries.

Linux: You can install Git through your distribution’s package manager. The APT package is called git-core; the package called ‘git’ is something unrelated.

Using Git

Creating an empty repository:

mkdir testrepo

cd testrepo

git init

Create a file called test.txt with the text ‘hello git!’. Then try ‘git status’:

bdon:testrepo Bdon$ git status

# On branch master

#

# Initial commit

#

# Untracked files:

#   (use "git add <file>..." to include in what will be committed)

#

#        test.txt

nothing added to commit but untracked files present (use "git add" to track)

bdon:testrepo Bdon$

git ‘sees’  the file test.txt, but it is untracked, meaning version control is currently ignoring it. ‘master’ refers to the current branch: this is a powerful feature we’ll use later, but for now just understand that the one branch you’re using is called ‘master’.

Tell git that you want to version the file:

bdon:testrepo Bdon$ git add test.txt

bdon:testrepo Bdon$ git status

# On branch master

#

# Initial commit

#

# Changes to be committed:

#   (use "git rm --cached <file>..." to unstage)

#

#        new file:   test.txt

#

bdon:testrepo Bdon$

Git is now prepared to record changes to test.txt (in this case, adding the new file). Now you can commit the change:

bdon:testrepo Bdon$ git commit -m "First commit"

[master (root-commit) 724941c] First commit

 1 files changed, 1 insertions(+), 0 deletions(-)

 create mode 100644 test.txt

bdon:testrepo Bdon$ git status

# On branch master

nothing to commit (working directory clean)

bdon:testrepo Bdon$ git log

commit 724941cacf6f983b3e46cb7643f50c29b110a143

Author: Brandon Liu <bran_liu@berkeley.edu>

Date:   Mon Aug 30 12:57:57 2010 -0700

    First commit

bdon:testrepo Bdon$

After we create a commit, Git assigns it a unique name (in this case, 724941c). ‘git status’ is empty now, and ‘git log’ shows us the commits we’ve made in the past.

Part 2: GitHub

GitHub is a web service (like what you’ll be creating in this class!) that hosts Git repositories remotely, and adds features to let engineers collaborate. It’s the most popular way for authors of Ruby gems to publish their work. GitHub has generiously sponsored private accounts for CS169.

Using GitHub

Once the staff has added you to your repository (It’ll be named cs169/firstname-lastname), you should able to navigate to it from your GitHub dashboard. You’ll see it listed on your dashboard in the right hand side under ‘Repositories’. (If you don’t see it you might need to “switch context” to the cs169 context.) Like this:

When you click on that link, you’ll be presented with the repository page.

Follow the directions under ‘Global Setup’ to get your account name and email into Git. Ignore the instructions under ‘Next steps’, Instead, clone the master assignment repository. located at http://github.com/cs169/assignments. This way, any time we update a skeleton file, you can use “git pull origin master” to merge in the changes.

git clone http://github.com/cs169/assignments.git

bdon: Bdon$ git clone http://github.com/cs169/assignments.git

Initialized empty Git repository in /Users/Bdon/Projects/githubtest/assignments/.git/

remote: Counting objects: 7, done.

remote: Compressing objects: 100% (4/4), done.

remote: Total 7 (delta 0), reused 0 (delta 0)

Unpacking objects: 100% (7/7), done.

This creates a directory called ‘assignments’ and checks out all the files. You will only need to do this once. Next time we update the skeleton, use ‘git pull origin master’ to bring your repository up to date.

Enter the directory that you just cloned (cd assignments)

Add your private repository as a remote branch named ‘private’

git remote add private git@github.com:cs169/firstname-lastname.git

(Tip: http://github.com git addresses are publicly readable, git@github.com are private)

Push code into your private repository on GitHub:

git push private master

 git push private master

Counting objects: 5, done.

Compressing objects: 100% (2/2), done.

Writing objects: 100% (3/3), 293 bytes, done.

Total 3 (delta 0), reused 0 (delta 0)

To git@github.com:cs169/brandon-liu.git

   da94a9b..6f316a2  master -> master

If you can browse your version of the skeleton on GitHub, great! Try changing a file like hw1/part2.rb, staging the change, commiting, and pushing to your private repository. You should see your commits reflected on GitHub.

Check out the file history features on GitHub. We encourage you to commit and push often to version your work; we’ll take a snapshot of your repository at the assignment deadline to grade it.