Introduction to Git for Development

Git is a free and open source version control software which is used for projects under the Railway-Op-Sim GitHub Organisation. When developing code or raw text based projects version control provides an essential means of storing, iteratively, changes made to files allowing the user to restore a project to a previous state should the need arise to reset it. Git also allows multiple developers to work on the same project simultaneously without risk of changes clashing. A project using Git for version control is called a repository.

Git logo

Developing with Git

There are two main ways to interact with Git, using a Graphical User Interface (GUI) based application such as GitHub Desktop, or the command line interface (CLI).

Development with GitHub Desktop

For those less familiar with using the command line, GitHub provides an application for interacting with repositories hosted on their service. The software is available here.

Installing Git CLI

Git for Windows is available to download on the software website.

When installing the software it is recommended that the Use MinTTY (the default terminal of MSYS2) option be selected as this provides a Unix BASH style terminal which is easier to use compared to the default cmd.exe application. After installation the Git Bash application is available within the start menu.

Introduction to Git CLI

All Git commands within this section must be run from within the project directory/repository.

Setting up Git in an existing project directory

When setting up a Git project make sure you are in the root (top level) directory for your project and run the following command:

git init

this initialises the repository and adds a hidden .git directory which will contain the archived project versions.

There is no set requirement for a remote server, Git can be used completely offline if you prefer to not upload files.

Setting a Remote Address

In order to be able to upload your project onto GitHub you need to firstly create a remote repository and then copy the clone URL. There are two options, either cloning using HTTPS which will require you set up a temporary access key, or SSH which requires setting up a more permanent SSH key, these are outlined here:

• SSH key generation.

To add the URL as the remote repository for your local project run:

git remote add origin <copied-url>

Creating a RailOS Project with Git

There is a drive towards standardising the directory structure with RailOS projects such that metadata can be parsed and files located with ease. As such it is recommend that projects be created using the template repository located under the RailOS GitHub organisation which can be found here. By clicking "Use this Template" you can create a new repository, if you plan on opening up to contributions from the community you can create the repository under the organisation itself. To do this you will firstly need to request to be added to the organisation.