Revision as of 11:53, 15 July 2009

This is an introduction to using git for OpenSim core developers.

Installing Git

Linux

Git is provided as a package with all modern Linux distributions. Install the following packages depending on environment:

• Debian, Ubuntu: git-core

Windows

On Windows you need to install 2 packages:

• msysgit - the basic git port for windows. Install this first.
• Tortoise Git - the git explorer. Install this second.

When installing msysgit be sure to choose Unix style line endings. This will make it so that all the line endings are managed correctly, which will prevent merge issues in the future.

Configuring Git

Git has both a global config and a local config for each repo. As one might expect, local trumps global. The first important thing to do is set your name and email address, as that will be used in your commits.

On Linux this is done via:

git config user.email YOUR@EMAIL.ADDR 
git config user.name "Your Name"

On Windows this done with the config menu.

Git Repositories for OpenSim

Current there are 2 git repositories on the system:

• an opensim-test repository, which allows for experimentation with git (this is not kept up to date with the latest svn trunk)
• an opensim git mirror of the svn trunk (this does now allow checkins, it is a direct mirror of the svn trunk)

The urls for the repositories are as follows:

Cloning the Test Repositry

There is a test repository on opensimulator.org in /var/git/opensim-test. This is a point in time capture of the opensim trunk (and all changes prior). It is designed for messing around with to get comfortable with git. Don't worry about breaking this repository.

The initial clone will take a few minutes, as the git repository contains the entire history of the project.

Linux

Run the following on the command line:

git clone ssh://opensimulator.org/var/git/opensim-test

This will create an opensim-test directory locally

Windows

Right click on the Desktop (or wherever) and 'Git Clone...'

When prompted for a url provide ssh://opensimulator.org/var/git/opensim-test. You username and password will be the ones used for opensimulator.org.

Conceptual Changes from Subversion

The first thing you should do is read the git / svn cheat sheet. This provides a very solid basis for making your changes. That being said there are some conceptual changes to note.

• Terminology
  • master is the name of the primary upstream branch (in subversion terms, this is trunk)
  • origin is the name and location of the tree you cloned from
• All repositories are full peers to all other repositories. Your cloned git repo is all the history of the entire project, available locally. It means you can sync between any 2 clones of the repository, not just between your clone and the master repo. This lets people work together on changes not in
• Version numbers are SHA1 hashes, not sequential integers. This means referring to specific revisions is a bit more interesting. For most of the git commands, you only need to give it the first 6-8 digits of the hash for them to work.
• Committing
  • commits are local. This means they are fast (no network involved) and they are committed against the last state of the tree. Any conflict resolution will be handled after commits, during your next pull. This is slightly different than pull-resolve-then-commit model of subversion.
  • by default only files you explicitly git add are put into the commit. To get svn ci equivalency use git commit -a to commit all outstanding files (I think tortoise handles this for you)
  • after making a commit you must then push it to a remote repository (probably origin). By default you push only branches you have previously pushed, typically master.

Subversion Like Workflow