First Steps with Gitorious and git

This file is intended for beginners with git.

A few details can be found at
http://wiki.centos.org/QaWiki/AutomatedTests/WritingTests/t_functional

Hopefully this file will answer the remaining questions

Git
---
Probably all available options on git can be found with "man git". Specific help on an option ie "git fetch" can be found with "git fetch --help"

Getting started with gitorious
------------------------------

First you need an account with gitorious:
https://gitorious.org/users/new
After registration you will receive an eMail to verify your eMail-Account. 

Afterwards you can login to gitorious

SSH-Keys
--------
If you intend to use SSH with git, you have to register your public key with gitorious. Go to  "Manage SSH keys" and then "Add SSH key". Copy the content of your key (home-directory/.ssh/id_rsa.pub or home-directory/.ssh/id_dsa.pub into the window and "Save".

Cloning t_functional
--------------------
At https://gitorious.org/testautomation/t_functional you will find the button "Clone repository". Next you will be asked for a name for your clone - pick a name at your descretion or use the suggestion. Klick "Clone repository" and you have your own copy of t_functional with an SSH-URL that looks something like this:
git@gitorious.org:<<username>>/testautomation/<<your clone-name>>.git.
The HTTPS URL looks something like this:
https://gitorious.org/<<usernamm>>/testautomation/<<your clone-name>>

To work
-------
To work with your copy, you have to create a local clone on your linux box.
"yum -y install git" should install all you need to use git.

Cloning:
"git clone <<SSH-URL>> <<destination-dir>>" will create a clone of your gitorious-repo on your local box. You will find your clone at <<destination-dir>>.
You should set at least two global settings:

git config --global user.name "your username"
git config --global user.email "your email"

All git operations work best if executed within your <<destination-dir>>.

Within the destination-dir you will find the folder .git. Go there and edit the config-file. Change your user-credentials and add:
[remote "upstream"]
	url = https://git.gitorious.org/testautomation/t_functional.git
	fetch = +refs/heads/*:refs/remotes/upstream/*
This allows you to update your clone from the t_functional-master in later steps.

Now to work with the test scripts :)
Lots of good hints to start with can be found ind doc/WritingTests and in the allready available scripts.

After you are satisfied with your work, it has to be commited.
New files will have to be added to git with "git add <<path-to-file/filename>>". You can also use "git add <<path-to-file/*>>".
A final "git commit --all" will open a vi-like editor. Please enter some comments regarding your changes. After exiting the vi your changes are commit.
Use "git push" to push theses changes to gitorious.

Merge request
-------------
Your push (or pushes) to git need to be merged with the t_functional master. This is done with the web-interface. On the webpage of your clone - something like https://gitorious.org/<<username>>/testautomation/<<your_clone>> - press the button "Request merge". Add some comments/notes, scroll down and select your commits up to the point you want to merge (you can keep the dropdown menues unchanged). "Create merge request" will do just that. On https://gitorious.org/testautomation/t_functional you will now find the number of "Merge requests" being increased by 1. Clicking on "Merge Requests" will show you all current and previous requests (possible states are Open, In Review and Closed).

Keeping in sync
---------------
With time your gitorious clone and your local copy will drift from the t_functional master (you work on your copy and others work on their copies/master, pushes/commits and merge request happen and so on). The best way to deal with this is to do a local merge of the current master and your local copy:
"git fetch upstream" will fetch the current t_functional master from gitorious.
"git merge upstream/master" will now merge your local copy with the previously fetched master. This effectively writes all master changes to your local copy.

If you work on two different machines - assuming you commit your work after it is done - you can do something similar to keep your second machine in sync with your work and not always have to delete your local copy and do a "git clone ..." again:
"git fetch origin" will fetch the current master of YOUR t_functional-clone from gitorious (not the t_functional master).
"git merge origin/master" will now update your local copy to the latest commit you pushed to gitorious.

During these operations you will also see the "version" numbers of the various commits. i.e.:
>>
me@centos:~/t_functional>git fetch origin
remote: Counting objects: 17, done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 9 (delta 6), reused 0 (delta 0)
Unpacking objects: 100% (9/9), done.
From gitorious.org:~<<USERNAME>>/testautomation/<<USERNAME>>s-t_functional
   4a5d56d..33951fe  master     -> origin/master
>>
The fetch operation downloaded the differences from 4a5d56d to 33951fe and put them in origin/master.

>>
me@centos:~/t_functional>git merge origin/master
Updating 4a5d56d..33951fe
Fast-forward
 tests/p_freeradius/0-install_freeradius.sh |    4 ++--
 tests/p_gcc/test_gcc.sh                    |   11 ++---------
 tests/p_php/10-php-test.sh                 |    3 +--
 3 files changed, 5 insertions(+), 13 deletions(-)
>>
Now my local copy should match the data available online.

At the time of writing this 33951fe is also the latest version available on the t_functional - master so:
>>
me@centos:~/t_functional> git merge upstream/master
Already up-to-date.
>>
There is no difference between the t_functional clone and the t_functiomal master so 'Already up-to-date' (as the last push to the master was the authors last commit to his clone and a subsequent merge request).

Last ressort
------------

If - for any reason - you are unable to sync your repos correctly, you can always delete your clone at gitorious and
create a new one.

Happy git'ing and testing!