Simple Use of Git for OpenSim Development

Git-Logo-2Color
Git is a source code version control supporting contributions from a number of developers. Git tutorial and reference material is available via including a complete online “Pro Git” book.

Contributions are made by “non-core” developers who can submit a “patch” attached to the OpenSim Mantis issue tracking system at http://opensimulator.org/mantis. These are reviewed by one or more OpenSim core developers who can, if appropriate, then approve and insert the patch to appear in the OpenSim Git development “master” at http://opensimulator.org/viewgit/

The notes here are the process I used, after a few experiments, to establish a simple Git environment and workflow on a Windows 10 desktop to allow me to create patches in the required form to potentially contribute to OpenSim.


Setting up the Git Tools, a link to the OpenSim Master Repository and Making a Branch for your Changes

Git-Desktop-Icons

  1. Create an account on GitHub.com if you don’t already have one. That will allow you to create a simple profile including the name, e-mail address and thumbnail image you want to use when making contributions to projects.
  2. Obtain and install GitHub Desktop (Windows or Mac) via https://desktop.github.com/. This creates two desktop icons, one for the GitHub GUI and one for a Git Shell (using Windows Power Shell) which work in harmony.
  3. Configure Git on launch to add in your GitHub username and e-mail which will be used to label contributions or patches you make. This creates [user] section “name” and “email” lines in your .gitconfig file. It can also be done using the Git Shell and using the commands…
    git config user.name "Your Name"
    git config user.email username@gmail.com
    
  4. If you have not already done so, launch the Git Shell and you can set the editor you wish to use to add messages into patches to one that can handle Unix line endings (which Windows Notepad does not). Note the editor executable must be on the Windows PATH. E.g.
    git config --global core.editor emacs
    
  5. OpenSim wants patches that do not add Windows style line endings. Automatic translation between the Unix line ending reporitory files and local Windows files is possible, but to be certain, I explicitly set this via…
    git config --global core.autocrlf false
    
  6. After these steps your C:\Users\username\.gitconfig file should have something like these entries… amongst others…
    [user]
    	name = Your Name
    	email = username@gmail.com
    
    [core]
    	autocrlf = false
    	editor = emacs
    
  7. Now, as a potential non-core OpenSim contributor you can establish a (read-only) “clone” of the main OpenSim Master Repository. I found the easiest way to do that was using the Git Shell” and typing in…
    git://opensimulator.org/git/opensim
    

    This also sets all the files as “tracked”. Changes to any of these files are monitored so they can be added to any commit. Newly added files though need to be explicitly handled (see later).

  8. Note that git://github.com/opensim at http://github.com/opensim is a mirror of the main repository at git://opensimulator.org/git/opensim but you should use the main repository as it will be up to date.
  9. With the default location for GitHub files of C:\Users\username\Documents\GitHub this will create a directory in C:\Users\username\Documents\GitHub which contains the OpenSim files and a special .git directory which supports all the Git operations, your commits and patch creation operations.
  10. The Git Shell by default starts in C:\Users\username\Documents\GitHub. You can change to work in a Github managed project simply by moving into its directory. E.g. into the “opensim” directory using…
    cd opensim
    

    Note that this will also show the current branch you are set to (initially “[master]“).

  11. While in Git Shell and set to the “master” you can also do a “pull” of the current OpenSim Master Repository content to your local filestore with…
    git pull
    

    You can use also this Git command at any time when set to the “master” branch to “sync” the OpenSim Master Repository files with your local copy.

  12. Also while in Git Shell create a branch off the opensim “master” called, for example, “mods” with…
    git branch mods
    
  13. You can change between the “master” and “mods” branches to work in using the Git Shell command…
    git checkout mods
    
  14. You can check the current status of your branch and whether there are outstanding modifications which are not yet committed using…
    git status
    

Git-Shell-opensim

Now you are all set to make changes, and to create patches from the changes you make. I found that the “GitHub” GUI tool was most useful from this point right up to the preparation of a patch, for which I swapped back to the Git Shell. Git settings and branch changes made in the Git Shell and GitHub Tool for any GitHub project are synchronised (the magic happens in the projects .git directory).


Make your Changes

At any time, independent of whether you are using GitShell or the GitHub Tool, you can make any changes you wish to the files in C:\Users\username\Documents\GitHub\opensim by directly editing them. It is suggested you use an editor (e.g. emacs) that does not change the Unix style OpenSim file line endings


Using the GitHub Tool

  1. Select “opensim” Repository – When you run the GitHub tool you can choose one of the repository is you have set up… the opensim repository will show in the left column, if you have performed a “clone” operation. More can be added via the “+” icon in the top left corner. But for some reason “remote” does not allow for connections to repositories that are not hosted on GitHub.com itself.
  2. Select “master” branch and “Sync” – You can select the “master” branch in the branches drop down menu near the top left. A “Sync” button in the top right corner allows you to synchronise the OpenSim Master repository files with the local copy. The “Sync” on the “master” branch in the GitHub Tool is the same as using “git pull” on the masdter branch in Git Shell.
    GitHub-opensim-master
  3. Select “mods” branch and “Update from master” – Select the “mods” branch you made for your own changes and perform an “Update from master” to bring in any changes made recently to the “master” repository so they are available in the version you will change.
    GitHub-opensim-mods
  4. Check if there are uncommitted changes – On the “mods” branch you can see a button in the top right saying if there are “No uncommitted changes” unless you have made changes you have made to the “tracked” files that are not yet notified to Git via a commit.
  5. Commit N uncommitted changes(s) – When you do have changes and want to create a single commit for all the changes.. hit the button and a panel opens to allow you to insert a short “Summary” and a longer “Description” of the changes you have made.
    GitHub-opensim-mods-commit-example

Making a Commit

  1. Ensure you are on the “mods” branch by selecting the “mods” branch in the GitHub Tool or in Git Shell use…
    git checkout mods
    
  2. Bring the branch up to date with “master” using the “Update from master” button in the top left of the GitHub Tool or in Git Shell use…
    git merge master
    
  3. Commit changes to all “tracked” files that are modified (so excluding any newly added files) using the “N uncommitted changes” button in the top right of the GitHub Tool and then using the form provided in the GitHub Tool or in Git Shell use…
    git commit -a
    
  4. Note that by default Git does not add all modified files during a commit. To add new files use:
    git add file1 file2 ...
    git commit
    

Creating a Patch

OpenSim development asks for patches to be prepared and attached to an OpenSimulator Mantis issue. The following commands create a patch for the last commit (-1) or changes between the current “master” – known as “origin/master” – and the commit labelled #hashtag is the one for the commit, usually 8 or so characters are sufficient to identify it) … and places the patch in a directory one up from the opensim repository files…

git format-patch -1 -o ..\tmp
  or
git format-patch -o ..\tmp -1
  or
git format-patch -o ..\tmp origin/master #f0e70490

Note that using –stdout > patch.txt does not work for opensim use as the line endings are Windows form)..

The results will be in C:\Users\username\Documents\GitHub\tmp

Inspect the patch to check it looks okay… an example follows…

Git-Sample-Patch


Submitting a Patch to the OpenSimulator Community

  1. Go to the OpenSimulator “Mantis” issue tracking web site at http://opensimulator.org/mantis and create an account there if you have not already done so, or login if you have.
  2. If your modifications relate to an existing Mantis issue add a comment and attach your patch file. If its a new issue create that and attach the patch file. In both cases amend the status to “patch attached” to draw the attention of the OpenSim core developers to your contribution. For a new issue, by convention, add the text [PATCH] to the front of the Mantis issue summary.
    OpenSimulator-Mantis-Issue-with-Patch-Example
  3. After the issue has been created or modified, so a final check that the patch looks okay expand the patch to “Show Contents” and especially watching out for extra blank lines, indicating that Windows CR/LF extra symbols have wrongly been added.
    OpenSimulator-Mantis-Issue-with-Patch-Example-Show-Content

OpenSim Core Developer Sign Off of a Contributed Patch

An OpenSim Core developer with appropriate permissions to commit directly to the remote master copy of OpenSim at http://opensimulator.org/viewgit/ may use a command such as the following to “sign off” a contribution…

git.exe am --signoff --ignore-space-change --keep-cr patch-filename

Reverting the Changes Made to Sync with Master – Better to Delete the Branch

As explained above, as a non-core developer you cannot directly commit changes to the remote master version of OpenSimulator. You are contributing potentially useful patches which might or might not be adopted. This can mean you have to constantly keep changing your “mods” branch to keep it in line with other changes in master. I tried to maintain a simple setup by using “revert” on each commit on the “mods” branch after creating the patch. A revert of the last commit (or any commit in fact) on the “mods” branch can be made very simply by selecting the commit and using the “Revert” button. But it turns out that this process does not allow “clean” patches to be successfully generated. The patches when applied try to refer to the commits/reverts that were in the branch history but not passed to the remote repository and give this message…

sha1 information is lacking or useless

Instead, I found its best to DELETE the “mods” branch entirely, using… (the capitalised -D flag forces the delete, so ensure you want to do that)…

git branch -D mods

Then go back and cerate a new branch “£mods” and work afresh in that for the next patch you wish to contribute.


Alternative workflow using Git Shell for actions performed in the GitHub GUI Tool

  • Resetting local master copy to remote contents. Ensure you are set to the opensim “master” branch.
    cd opensim
    git checkout master
    git pull
    
  • You can edit the message associated with the last commit using the GitHub Tool by clicking on the commit or using the Git Shell command:
    git commit --amend
    
  • You can see the master and any branches that exists using the GitHub Tool or using the Git Shell command:
    git branch
    

Update 21-Dec-2029: Helpful Short Introduction to Git Desktop
by Fred Beckhusen

Without a lot details, this is a short summary how it works. Git is a distributed repository of every change. If Github went away, anyone with a git clone of the repo still has a complete copy of it along with every change, including any deleted files. This is one of the reasons why we must be careful to only commit properly licensed items in git. It will be there forever.

You install the git program from https://git-scm.com/ on your PC using the defaults. Git has its own DOS-like command box as well as a GUI. For example, to start on the Ruth/Roth Git repository, you shift-right click an empty folder and select “Git Bash Here”. In the box that appears, you type git clone https://github.com/RuthAndRoth/Ruth.git

It will fetch and give you a copy every change ever made. You can repeat this at any time the latest version by typing ‘git pull’. This is about the only reason to use the DOS box for beginners. So you can close it.

You make any changes you want to that folder. Add, delete rename, edit. You should keep your changes as a unit – e.g., do one unitized thing at a time. Then ‘commit’ the changes. For example, make a new folder and put stuff in it. Or edit and save a Blend file. Each commit is recoverable. So if you commit a mistake, no worries, just fix it, and commit a corrected version. Each commit requires a simple comment so people know what that commit has in it.

One huge advantage of git is there is no need to keep saving more and more copies of a Blend that is a work in progress. Or keep old stuff that should really be deleted. One copy of something is usually enough, so long as you commit it often, as git will remember every one you commit. So if you really screw up, you can always check out an earlier version and work from there.

After each change, you should use the Git GUI to commit it. Right click the folder and select Git GUI Here.

There are buttons at the bottom to rescan the disk for changes you made. Stage them to the “Will commit” box, which sets them to be committed as a batch. You can stage and unstage with keystrokes or a menu until you have the files you want in one batch. I often forget to commit, so I can break up the changes and commit them separately.

Sign it, then Commit it to your local PC’s copy of git. You can commit many things there, and keep a local history of all your changes.

When you are ready for the github to have a copy, click “Push’ to push the changes to the github.

This entry was posted in OpenSim and tagged , . Bookmark the permalink.