Mac OS X

Or you can even obtain GitX GUI tool from GitX Website and put it into application folder.

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.

Git Repositories for OpenSim

Cloning the Repositry (for Core Developers)

If you are a core developer, use the developer url above. If you aren't a core developer, use the anon url above. The initial clone will take a few minutes, as it is pulling the entire change history. Don't be concerned about space, all the change history stored in git takes up less space than a single checked out copy of opensim. Welcome to the wonderful world of content addressable storage.

Unlike with svn, you can define multiple sources to pull from. So if you initially start with an anon tree (which is read only), you can still later define the core tree (or some other remote target on github) and push to that.

Linux / Mac OS X

Run the following on the command line:

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

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. You username and password will be the ones used for opensimulator.org.

Cloning the Repositry (for Non Core Developers)

Resolving git hash & revision numbers

These generate the bin/.version file which is used to identify the Git-Hash Revision. The GIT Hash is used to track the builds for troubleshooting and for filling Mantis Reports. Without proper Version Identification developers / contributors cannot locate & address problems within the source code, resulting in un-usable Mantis reports. Please Version your Builds to help everyone make a better OpenSimulator.

NOTE: Older installation of GIT such as 1.6.0.4 do not support the extra functions. To make use of the above scripts it is recomended you update your GIT installation to the most current revisions. They are available from git-scm.com/

Conceptual Changes from Subversion

Distributed source code control is a substantially different mental model than centralized source code control. If it freaks you out a bit, don't worry, everyone has that same reaction initially. This blog post is the best explanation that I've seen of the concepts involved.

For heavy users of subversion you should 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.

The biggest real change is the Subversion dictates a very specific workflow. Git does not. Git allows for many different workflows, and lets each developer use the one that is best suited to his/her self.

Using Git like Subversion/trunk development

This is a set of quick instructions to use git like we do subversion development today. It is targetted for core developers (so assumes you are using the ssh access), though most of it will work for non developers by just changing a url.

This is done by giving the unix commands. These options should all be available in the context menu on tortoise git as well.

Getting the source code

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

This is the equivalent of svn co

Note: all other operations assume that you are in the git directory.

Updating your checkout

git pull

This is the equivalent of svn update

Inspecting what has changed in your working tree

git status

This is the equivalent of svn status

Committing a change

either:

git add file1 file2 ...

git commit

or

git commit -a

by default git does not add all files during a commit.

Pushing the committed change

The first time you do this you'll need to specify which branch to push.

git push origin master

After the first time a simple git push will be enough, as it defaults to origin, and now git knows that master should by synced to origin.

Important: commits in git are local. They are not included in the main tree until you push them. This means you can create commits when you are not on the network and sync afterwards.

Setting the checkout dir to a specific revision

git reset --hard #HASHVALUE

This will effectively rewind the tree to the specific revision, and modify the checkout dir accordingly. This is equiv to svn up -R#version.

git reset can also be useful if you screwed up commits and want to get rid of them

Resetting the tree to master (i.e. trunk)

git pull

per previous

Creating a Patch

git format-patch #HASHVALUE

This will create a patch suitable for attaching or emailing from a single commit. You can also specify a range of commits.

This is closest to svn diff > patchfile.txt for uncommitted changes in subversion.

Applying a Git Patch

If someone has formatted a git patch you can apply it directly (including all file adds, file mode changes, and their change log entry) with:

Resetting part of the tree to master

git checkout -- file1 file2 ...

Checkout is an operation that populates the working directory from the git repository. Doing a git checkout (master is the implied branch) -- file1 file2 repulls those files from the git repo, clobbering them in your local directory. This is like svn revert.

Diffing Changes

Against your most recently committed changes

git diff

From your most recent changes to a past change

git diff #HASHVALUE

Between any 2 changes

git diff #HASHVALUE1 #HASHVALUE1

Branches

Creating a Branch

To create a new branch based on the current one, do:

git branch <branchname>

Changing Branches

To change between branches do:

git checkout <branchname>

Tracking a Branch

If you want to work on a specific branch, you can track it, by creating a local version of it on which you can pull and push. If you have already pulled (or fetched) from origin, you should have all remote branches names:

git branch -a

Will show all branches, local and remote. Choose a remote branch to track then do: