"Git" is a powerful, free system for managing code as it's worked-on by a distributed group. It allows a group like JMRI to cooperate effectively. We keep the JMRI code, help files, sample scripts, XML files, etc. in a Git repository hosted on GitHub.com. The JMRI web site is in a similar repository.
You can browse the JMRI code directly on that site. For example, if you'd like to look at this page, click this link to display its source HTML code.
If you want to suggest a change to a file, for example a web page like this one, first get a free GitHub account and sign in.
Then go to the file you want to change and click the pencil icon on the upper-right of the
page.
This will, after a second or two, give you a page where you can edit the contents of the file with your suggested change. Don't worry, you're not actually changing JMRI's original code, just your personal copy of the code.
Then fill out the form at the bottom with a useful subject line, and a description of why
this is a good change, and click the "Propose file change" button. This saves your edits to
your personal copy on the Git server.
Next, click on the "Pull request" button at the top right of the code panel. This sends your
change to the people who've agreed to maintain the JMRI central code, who will review and
(usually) include it in the next JMRI release (more
details).
Our source code is distributed using Git. (We also keep the website in Git, if you'd like to work with the source for that directly.) If you want to work with the JMRI code, the full web site, or any other large part of JMRI, spending a couple minutes getting Git set up is well worth it. We're sorry, but we just can't support other methods (sending around individual files, etc.), as they're just too error prone.
Although there are lots of ways to use Git, the next sections show the most common ones:
If you want to develop changes to the code, see the "Developing with JMRI Code" page.
Also check the JMRI Git FAQ page.
The GitHub Desktop application is a very convenient tool for working with Git repositories. Unfortunately, it's only available for Mac and Windows. For Linux, please use one of the other methods.
After the download is complete, there are menu items under the application "Repository"
menu to access the code directory:
You can also navigate there directly using your file system.
Inside, you'll find directories called xml, resources,
jython, help, lib, java and others.
In the java directory, you will find a src directory that
contains the source code for JMRI itself, and a tests directory that contains
various test routines.
You can look at the code with your favorite text editor.
To compile and run the code, you need one of the compilation tools described on the bar at
the left: Ant, Eclipse, NetBeans, IntelliJ, etc. (Ant may be the
easiest to install and use, and is the primary example in the documentation)
For more information on using the GitHub Desktop application, please see the our page on using GitHub Desktop and the Git FAQ help page.
First, check whether Git is installed on your computer. From a command line, do
git --version (note the two hyphens).
If it replies with a version greater than 2, e.g. 2.3.8, you're all set. If not, there are
instructions for installing Git in the Git FAQ. Install Git, then come back here.
To get a local copy of the code, you tell Git to "clone" it from our repository. The command to do that is:
$ git clone https://github.com/JMRI/JMRI.git
This will create a new "JMRI" directory and download the code into it.
If you have already gotten a copy of the code on your computer and want to update it to the most recent contents of the main JMRI repository, start in the JMRI code directory and to:
$ git pull https://github.com/JMRI/JMRI.git
After the checkout is complete, go to the new JMRI directory that was created. Inside,
you'll find directories called xml, resources, jython,
help, lib, java and others.
In the java directory, you will find a src directory that
contains the source code for JMRI itself, and a tests directory that contains
various test routines.
You can look at the code with your favorite text editor.
To compile and run the code, you need one of the compilation tools described on the bar at the left: Ant, Eclipse, NetBeans, IntelliJ etc. (Ant may be the easiest to install and use, and is the primary example in the documentation)
Most IDEs have Git support build in. For the ones that can build JMRI, we have specific instructions:
The best way to retrieve the source for releases 4.1.2 and earlier is from the SVN Repository (see the link for details.
The best way to retrieve the source for releases 2.12 and earlier is from the CVS Repository (see the link for details.