h1. Git-maus

Besides Launchpad and bazaar MAUS has beta level support for git and"github":https://github.com/mice-software/maus. At the moment code updates for the trunk cannot be accepted from github however, only via Launchpad and bazaar.

h2. Overview

This following section will guide you to:

# Create an account on GitHub

# Add an ssh key to your account

# Fork the MAUS repository on github into your personal github account

# Make a local copy on your computer of your fork of MAUS

# Create a new development branch within this repository locally

# Make and changes and commit these changes to this branch

# Push your development branch and these changes to your github MAUS fork

# Create a Jenkins test server job for your development branch

# Propose merging your changes back to the MAUS trunk via github

# Merge changes from the MAUS trunk into your development branch

h2. Step-by-step guide

# Create an account on "github":https://github.com/

# "Add an ssh key":https://help.github.com/articles/connecting-to-github-with-ssh/ to your account

# Fork the MAUS repository on github into your personal github account

## Go to "MAUS github page":https://github.com/mice-software/maus and login into github

## Click "Fork" in the top right of the screen, selecting the option to fork to your own account

    !http://micewww.pp.rl.ac.uk/attachments/8360/GitHubForkScaled.png!

## Select your own account from the options that appear for where to fork MAUS

# Make a local copy (clone) on your computer of your fork of MAUS

## Copy the address of your new fork from github (something like @git@github.com:jbloggs/maus.git@, where jbloggs is your github username)

## Clone your repository:

<pre>

git clone git@github.com:jbloggs/maus.git

</pre>

where jbloggs is your github username.

# Create a new development branch within this repository locally

## cd into the directory created by the clone command (maus by default)

## Take a look at the branches present with:

<pre>

git branch -av

</pre>

## Pull down the merge branch from your remote github repository into the new local repository:

<pre>

git checkout merge

</pre>

## Create a new development branch in the local repository by forking the merge branch:

<pre>

git checkout -b my-feature-branch

</pre>

## Observe the new state of your local repository with:

<pre>

git branch -av

</pre>

A note on nomenclature: The original repository you fork from on github is usually referred to as the @upstream@ repository. Any repository you clone from is by default named @origin@. Here @upstream@ refers to the central MAUS github repository, and @origin@ refers to your fork of it on github.

# Make changes and commit these changes to the local development branch

## Edit some files, creating some wonderful new feature for the benefit of mousekind

## Stage the changes:

<pre>

git add AlteredFile1.cc AlteredFile2.cc

</pre>

## Commit the changes:

<pre>

git commit -m 'My excellent new feature, closing issue ###'

</pre>

# Push your development branch and these changes to your github MAUS fork

<pre>

git push origin my-feature-branch

</pre>

# Create a Jenkins test server job for your development branch

## The MAUS test server can be found at: "http://test.mice.rl.ac.uk":http://test.mice.rl.ac.uk

## Either email the head of MAUS requesting a test branch and giving your repository url and development branch id, or go to the test server, create a new item, copying an existing git-based test job, and edit the configuration with your repository url and branch name

# Propose merging your changes back to the MAUS trunk via github

## Run the Jenkins test server job on your development branch

## When Jenkins has passed (and not before), return to your repository page on github and select @my-feature-branch@ from the drop-down menu on the left (below is an example where the feature branch is named "event-selection")

    !http://micewww.pp.rl.ac.uk/attachments/8362/GitHubBranchesScaled.png!

## Click the "Pull request" button to propose merging into the trunk

## Make sure your branch is comfortable for merging, that is it does not lead to any conflicts when github attempts a mock merge into the central MAUS merge branch. If your branch is not comfortable for merging, edit some more until it is, commit and push, then try again

## Creating a pull request will alter the MAUS maintainers you want your code added to the trunk, and begin a conversation between you and them if any changes are required first

# Merge changes from the MAUS trunk into your development branch

## One reason your development branch may not automatically be comfortable for merging back in the central MAUS merge branch is if someone has pushed changes there since you forked your repository. This can be dealt with by merging the changes from the central MAUS repository into your repository.

## First, we must tell your local copy of your repository about the central MAUS repository on github. This is called adding are remote. Note your local repository already has one remote, your repository on github - it has the default name @origin@. Add the central MAUS repository on github as a new remote called @upstream@ with:

<pre>

git remote add upstream git@github.com:mice-software/maus.git

</pre>

## Look at your repository structure again with:

<pre>

git branch -av

</pre>

## Make sure we are in our feature branch:

<pre>

git checkout my-feature-branch

</pre>

## Now merge from the central MAUS merge branch into your feature branch with:

<pre>

git pull upstream merge

</pre>

## If there are any conflicts listed, examine each file in turn, make the changes needed, and then resolve the conflicts with:

<pre>

git add MyFixedFile.cc

</pre>

Commit the changes made if you resolved conflicts with:

<pre>

git commit -m 'Merged from the trunk'

</pre>

## Now push the changes back to your github repository with:

<pre>

git push origin my-feature-branch

</pre>

h2. Useful git commands

See "https://www.git-tower.com/blog/git-cheat-sheet/":https://www.git-tower.com/blog/git-cheat-sheet/