View source for Introduction to Git for Development

[https://git-scm.com/ Git] is a free and open source version control software which is used for projects under the [[Developer GitHub Organisation|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.

[[File:Git-logo-2012.svg|thumb|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 [https://desktop.github.com/ here].

=== Installing Git CLI ===

Git for Windows is available to download on the software [https://gitforwindows.org/ website].

When installing the software it is recommended that the <code>Use MinTTY (the default terminal of MSYS2)</code> option be selected as this provides a Unix BASH style terminal which is easier to use compared to the default <code>cmd.exe</code> 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:

<code>git init</code>

this initialises the repository and adds a hidden <code>.git</code> 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 [https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository 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:

* [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent SSH key generation].


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

<code>git remote add origin <copied-url></code>

== 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 [https://github.com/Railway-Op-Sim/UN-Template 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.