rubinius

The Rubinius project uses the Git SCM. Committers need to use git to commit their code directly to the main repository.

This page contains information on getting Git installed, getting source code with Git, and steps for working with Git.

Also, see these references: Git - SVN Crash Course and Everyday GIT With 20 Commands Or So

Getting Git for Your System

You can use an earlier version, but 1.5.x is definitely recommended.

• MacPorts has 'git-core'
• Debian has 'git-core' (If you're using Etch, you can get a recent Git version from Backports http://backports.org/dokuwiki/do...)
• FreeBSD has 'devel/git' (I had issues with 1.5.3.2 am using source .7 instead --rue)
• Get the source at http://git.or.cz/

Setup

Configure Git with your proper name and email. This will display when you submit changes to the Rubinius repository.

git config  --global user.name "My Name"
git config  --global user.email "my@email"

If you prefer to use different credentials for different projects, you can also configure the above for a single repository only. See the git documentation.

Formatting Git Commit Messages

In general, use an editor to create your commit messages rather than passing them on the command line. The format should be:

• A hard wrap at 72 characters
• A single, short, summary of the commit
• Followed by a single blank line
• Followed by supporting details

The supporting details could be a bulleted enumeration or an explanatory paragraph. The single summary line helps folks reviewing commits. An example commit:

Fixes for Module#make_my_day return values.

* Return nil when passed ':('
* Return true when passed ':)'
* Updated specs for #make_my_day for nil argument case
* Updated CI excludes.

Getting the Code

Getting the code is easy once you have git installed but is slightly different depending on your access. In both cases that exact command will put the repository in a local directory called code. You can give it a different name just by appending it to the command.

New Users and Developers

git clone git://github.com/evanphx/rubinius.git         # Notice forward-slash
git clone git://github.com/evanphx/rubinius.git rbx     # Creates ./rbx instead of ./rubinius

Existing Committers with Commit Bit

git clone git@github.com:evanphx/rubinius.git        # Notice colon
git clone git@github.com:evanphx/rubinius.git rbx    # Creates ./rbx instead of ./rubinius

Commit Rights

New Committers

The policy is that if you give us one patch that is accepted and committed, you are eligible to get the "commit bit" which allows you to then start committing directly. In order to create that patch file, see instructions after the Workflow section. Once your patch has been committed, contact evan (IRC will be easiest, PST hours) and let him know. You will want to have the commit hash (more on this below) and the ticket ID handy for him in case the person who committed the patch is not available. Once verified, evan needs your public SSH key (~/.ssh/id_rsa.pub) so paste it into one of the paste sites if it is not up on the web already and give the URL to evan.

Existing Committer from SVN Days

If you are an existing committer but have not been set up on git, paste your ssh public key (~/.ssh/id_rsa.pub) into one of the paste sites and give evan the URL.

Git Workflow

Working with Git is significantly different that working with SVN. In particular, although similar, git pull is not svn update, git push is not svn commit, and git add is not svn add. If you are a SVN user, be sure to read the man pages for the different git commands.

The following workflow is recommended by Evan and is the guideline for contributing code to Rubinius.

1. Create a local working copy of the source code (we did this earlier.)

   # See above for the exact invocation
   

2. Change to the newly created directory that contains the local working copy. (Substitute the directory if you created it with a different name, obviously.)

   cd code
   

3. Create a branch for your work. This will make a copy of the current branch (master) and name it "new_feature". Now you can work in this new branch without breaking the main one.

   git checkout -b new_feature
   

4. Edit the code and test your changes. Then commit to your local working copy

   git commit -a
   

5. When you are ready to send your local changes back to the Rubinius repository, you first need to ensure that your local copy is up-to-date. First, ensure you have committed your local changes. Then switch from your topic branch to the master branch.

   git checkout master
   

6. Update your local copy with changes from the Rubinius repository

   git pull
   

7. Switch back to your topic branch and integrate any new changes. The git rebase command will save your changes away, update the topic branch, and then reapply them.

   git checkout new_feature
   git rebase master
   

   Warning! If you are sharing a branch, you must use:

   git merge master
   

   Rebase causes the commit layout to change and will confuse anyone you've shared this branch with.

8. If there are conflicts applying your changes during the git rebase command, fix them and use the following to finish applying them

   git rebase --continue
   

9. Now, switch back to the master branch and merge your changes from the topic branch

   git checkout master
   git merge new_feature
   

10. You might want to check that your commits ended up as you intended. To do so, you can have a look at the log

    git log
    

11. Get your changes in the main repository. If you have commit rights, you can just use the git push command. Otherwise, see the section below for information on creating a set of patches to send.

    git push
    

12. At this point, you can delete the branch if you like.

    git branch -d new_feature
    

When you're familiar with the workflow, you can use the rake tasks to help you out. For example, rake git will fetch the latest code from remote repo, rebase the current branch to master, fast-forward the changes to master and push the commits to the remote. This saves a lot of typing. Check rake -T git for all the git related tasks.

Patches: git-format-patch

If you are a new committer (or want to create a patch instead of directly pushing the code for some other reason) you should create a patch file for your commits. The patch file should be then attached to a ticket on Lighthouse (see the ticket writing howto for instructions for more details on that.) You can also send the patch to the mailing list but use the ticket tracker if at all possible. Either way, the patch file(s) should be created using Git.

First, make your changes as detailed below and then use the git format-patch command to create the patch files. Usually using the command is as simple as specifying the commits you want to create patches for, and that is done in one of two ways: by giving a range of commits or a starting point. As mentioned earlier, each commit is identified by a unique hash ID which you can see, for example, by looking at the git log output. You can generally shorten it -- first 8 should be plenty -- because it is unlikely to conflict (if it does, just use the full ID instead.) In my examples below I just use imaginary IDs. Let us say you created three commits, in this order my1stcom -> my2ndcom -> my3rdcom (and that the patch before those is notmycom):

• Specify a range of revisions. You can use the syntax git format-patch my1stcom..my3rdcom to include the first, the last and any inbetween. Alternatively, you could use git format-patch my1stcom..HEAD and other variants instead.
• Specify a single revision. This takes all patches following the one given. The only possibly unintuitive part here is that the revision you give is the last patch you do not want to include. For example, if you do git format-patch my3rdcom or git format-patch HEAD there will be no patches since there have been none since. In our case, you would want one of the following: git format-patch notmycom , git format-patch my1stcom^ , git format-patch HEAD^^^ or git format-patch HEAD~3 (or any of the other possible variations.)

(In Git terminology, HEAD is the last commit in your current branch. Parent patches can be referenced either by using a caret so that HEAD^ is one before HEAD and HEAD^^ is one before one before (i.e. two before) HEAD which gets cumbersome after the second or third caret; or by tilde-number: HEAD~1 is one before HEAD, HEAD~5 is five before HEAD and much easier to use. The caret and tilde can be used for commit hashes as well. For other variants, see the git-rev-parse man page.)

Whichever way you decide on, a separate patch file is produced for each, named [number]-[first line of commit message].patch. You can then attach these to a ticket (or e-mail them.)

Rake git Tasks

The above workflow has been wrapped up into a some rake tasks. The simplified version is:

Create a branch:

rake git:topic

Make your changes

Commit as needed:

git commit -a

Push your changes to master:

rake git:push