Git

Git

ROMS source code is distributed using both Git and Subversion(SVN). For details on using Subversion can be found here. There are command line and GUI Git clients available for nearly every operating system and a list of popular clients can be found here. This page will help you get started with downloading ROMS with Git.

Git Overview

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. All the ROMS/TOMS files are stored in a Git repository on www.myroms.org with access controlled by requiring authentication with the same ROMS Username/Password combination assigned to registered users of the ROMS Forum.

This Git repository is the official version of the code which only the developers are allowed to change. Users should download the ROMS code to their local machines using a git client. Don't attempt to use a regular web browser to browse or download files from the Git repository - there are much better tools for interacting with the code repository. See the notes below under the heading View the Repository.

We strongly recommend users always check out the current master version since this has the most recent updates and bug fixes. The tags are kept largely as a historical record of stable releases at the conclusion of major code upgrades.

Below is a general description of how Git works. Please look at the Pro Git book for more detailed information. We have not yet tried any GUI clients but may add brief how-tos for the most popular GUIs at a later date.

Downloading ROMS

WARNING: It is strongly suggested that you clone the ROMS source code using the same operating system you wish to compile and run ROMS on. If you download the code on a Windows machine and wish to run it on a non-Windows machine you will need convert the line endings with a utility like dos2unix or recode. Even with these utilities you may still have problems compiling ROMS.

In order download source code from a git repository, git client software must be installed on your local machine. Most Linux distributions come with git, so shell commands may be used without installing additional software. The general form of git commands is:

   git action <repository>

To check-out the files from the ROMS repository master (latest version), enter (notice https instead of http):

   git clone https://www.myroms.org/git/src MyDir 

where MyDir is the destination directory on your local computer. It will be created if not found. If your want to avoid typing your username for all future code updates, change the command to:

   git clone https://joe_roms@www.myroms.org/svn/src/trunk MyDir

You only clone once because Git will keep track of the source, destination and a bunch of other information. For more detail on command line use and syntax, see the Pro Git book.

Several GUI front-ends to Git exist, allowing the user to have visual prompts to help them manage their files and credentials.

Updates

Now and again, you might feel the urge to get up to speed with the latest changes that have been made to the ROMS repository. When that happens, simply go to the directory that was "MyDir" above and type:

   git pull

Subversion will remember where you checked out from before and see if a newer revision exists. If so, it will download and apply all the relevant changes.

Saving ROMS login credentials

There are a few different options for storing your ROMS login credentials in order to avoid having to type your username and password for every command. See here for more details.

Using GUI Git Clients

WARNING: It is strongly suggested that you checkout the ROMS source code using the same operating system you wish to compile and run ROMS on. If you download the code on a Windows machine and wish to run it on a non-Windows machine you will need convert the line endings with a utility like dos2unix or recode. Even with these utilities you may still have problems compiling ROMS.

Once we have some experience with some GUI Git clients, we will add to this section.

View the Repository

The easiest way to view a repository is to simply look at it with Trac in a web browser. Enter the URL:

https://www.myroms.org/projects/git-src/login

and log in with your ROMS credentials. Once logged in click the Browse Source tab near the top of the page. This is also a good way to see individual files in the repository without actually downloading them.