Using Git

The DataMapper 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:

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…)
Get the source at http://git-scm.com/.

Setup

Configure Git with your proper name and email. This will display when you submit changes to the DataMapper 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

DataMapper is hosted at GitHub. 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 dm. You can give it a different name just by appending it to the command.

New Users and Developers

git clone git://github.com/datamapper/dm-core.git

Committers with Commit Bit

git clone git@github.com/datamapper/dm-core.git

Git Workflow

Working with Git is significantly different than 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.</p>

The following workflow is recommended by Rein and is the guideline for contributing code to DataMapper.

Create a local working copy of the source code (we did this earlier.)
```
    # See above for the exact invocation
    
```
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 dm
   
```
Create a branch for your work. It is important that you do your work in a local branch, rather than master.
```
    git checkout -b new_feature
    
```
Edit the code and test your changes. Then commit to your local working copy.
```
    git add .
    git commit
    
```
When you are ready to send your local changes back to the DataMapper 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
    
```
Update your local copy with changes from the DataMapper repository
```
    git pull origin master --rebase
    
```
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 have shared the topic branch publicly, you must use
```
    git merge master
    
```
Rebase causes the commit layout to change and will confuse anyone you’ve shared this branch with.
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
    
```
Now, switch back to the master branch and merge your changes from the topic branch
```
    git checkout master
    git merge new_feature
    
```
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
    
```
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 origin master
    
```
At this point, you can delete the branch if you like.
```
    git branch -d new_feature
    
```

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. You can also send the patch to the mailing list but please 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.

For our purposes, the simplest way to create a patch is to begin at the end of step 8 above (after you have rebased your branch) and then, instead of merging:

git format-patch master..

This will create a separate patch file for each commit in your working branch that is not in master, named [number]-[first line of commit message].patch. You can then attach these to a ticket (or e-mail them).

You can also inspect your changes using git log master.. or git diff master.. to ensure that the patches will be generated correctly if you are uncertain.