Latest revision as of 10:25, 14 August 2023

This is an introduction to using git for OpenSimulator. If you just want to know the git cloning path, jump to #Cloning the Repository (for Non-Core Developers).

[edit] Installing Git

[edit] Linux

[edit] CLI

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

• Debian, Ubuntu: apt-get install git-core
• Centos: see the instructions at http://www.how-to-linux.com/2009/01/install-git-161-on-centos-52/

[edit] GUIs

git-gui

• Debian, Ubuntu:

$ sudo apt-get install git-gui
$ git gui

git-cola

• Debian, Ubuntu:

$ apt-get install git-cola
$ git-cola

[edit] Windows

Git is now integrated in recent Visual Studio versions. You can install it with Visual Studio Setup. Tortoise Git may still be useful.

Alternatively, you need to install two 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 manage all the line endings correctly, which will prevent merge issues in the future.

[edit] macOS

If you have MacPorts installed, then open a Terminal window and run:

sudo port install git

Or you can even obtain the GitX GUI tool, either using sudo port install GitX, or as a direct download from the GitX Website and put it into application folder.

Alternatively, if you use the more popular Homebrew package manager, the command to run from Terminal is:

brew install git

Note that Apple already includes its own git under /usr/bin/git — usually several versions behind (but nevertheless fully functional). Homebrew will not overwrite Apple's own git. Instead, it will be symbolically linked to /usr/local/bin/git — it will be up to you to configure your shell to execute applications from /usr/local/bin/ before /usr/bin (by default, the reverse is true).

GitX is also available via Homebrew:

brew install GitX

Finally, note that, unlike MacPorts, Homebrew is not invoked with sudo (mostly for security reasons).

[edit] 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 / macOS this is done via:

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

On Windows this is done with the config menu.

To setup your Context Menu to make your options easier, select the Context Menu options as shown above and choose what you want to have displayed immediately.

[edit] Git Repositories for OpenSimulator

The URLs for the repositories are as follows:

[edit] Cloning the Repository (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 needs to pull 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 OpenSimulator. 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/GitLab) and push to that.

[edit] Linux / macOS

Run the following on the command line:

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

This will create an opensim-test directory locally.

[edit] Windows

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

When prompted for a URL provide ssh://opensimulator.org/var/git/opensim. Your username and password will be the ones used for opensimulator.org.

[edit] Cloning the Repository (for Non-Core Developers)

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

This is the equivalent of anonymous svn access.

[edit] 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.

Windows batchfile

Linux bash script

NOTE:  Older versions 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 version.  All versions are available from git-scm.com/.

(Note from 2023: if you're really using such a Jurassic version of git, you must upgrade to a newer one! At the very least, pick one from the 2.X branch).

[edit] 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 master before submitting them.
• 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 that 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/herself.

[edit] Using Git like Subversion/trunk development

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

The instructions below are given using the command-line tool git. These options should all be available in the context menu on Tortoise Git (and on other GUIs) as well.

[edit] 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.

[edit] Updating your checkout

git pull

This is the equivalent of svn update.

[edit] Inspecting what has changed in your working tree

git status

This is the equivalent of svn status.

[edit] 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.

[edit] Pushing the committed change

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

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.

[edit] Setting the checkout directory 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 equivalent to svn up -R#version.

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

[edit] Resetting the tree to master (i.e. trunk)

git pull

per previous

[edit] 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.

[edit] 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:

preferred method (preserves creator info): git am --signoff patchfile.patch

this also works (try above method first): git apply patchfile.patch

[edit] Reverting a Change

git revert #HASHVALUE

This directly reverts the change, with a commit message stating that fact. There is no svn direct equivalence, though this is often accomplished through: svn diff -R revisions > revert.patch && patch -p0 < revert.patch && svn ci -m "reverting revisions"

[edit] 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 re-pulls those files from the git repo, clobbering them in your local directory. This is like svn revert.

[edit] 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

[edit] Branches

[edit] Creating a Branch

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

git branch <branchname>

[edit] Changing Branches

To change between branches, do:

git checkout <branchname>

[edit] 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 the names for the remote branches:

git branch -a

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

git branch --track <localbranchname> remotes/origin/<remotebranchname>

A new local branch will be created, which will push and pull to the specific remote branch.

• Alternate method that also works:

git checkout -b <wanted_branch> origin/<wanted_branch>

[edit] Resources & References

• Git - SVN Crash Course at git-scm.com/course/svn.html
• Git for the lazy tutorial at www.spheredev.org/wiki/Git_for_the_lazy
• Git video tutorials at http://gitcasts.com/  (several excellent video tutorials)
• The Git Community Book at http://book.git-scm.com/
• Git reference, documents and videos and Git Cheat Sheet
• The git-svn(1) Manual Page (git-svn = Bidirectional operation between a single Subversion branch and git)
• The Git-Svn Cheat Sheet