Brief git guide

Latest revision as of 12:28, 28 July 2011

Git is handy version control for collaborative development and testing. This guides you briefly through basics to get started. Only terminal usage under GNU/Linux is covered, for graphical user interfaces please refer guides available at web.

Note - this was not placed under developer nor testing because it's common for all MeeGo contributors.

Concepts

Please open the excellent git cheat sheet. Work flow is illustrated in the upper-right corner of cheat sheet. The most basic flow with an existing repository goes like:

1. Create

git clone <repository>

Example:

git clone git://gitorious.org/meego-quality-assurance/handset-ux-tests.git

2. Change

<edit or create files with your favorite tools / editors>

3. Commit changes

git add <newfile> (if you created new file)
git commit -a 

Your default editor is opened and you need to write description of changes.

4. Push changes to share

git push (this assumes you have commit rights to repository, please check with repository admin)

That's it! Congratulations!

Pre-steps

Mandatory - Make sure you have git installed

Debian/Ubuntu:

sudo apt-get install git

Optional - If working behind ssh-proxy

If you are working with corporation you might need to resolve ssh-proxy challenge.

Make sure you have following $USER/.ssh/config for your user account

host proxy 
 HostName <yoursshproxyhere>
 user <youruseraccounthere>
 Compression no
 LocalForward 2227 gitorious.org:22
host gitorious.org
 User git
 HostName 127.0.0.1
 Port 2227
 

Run the following command:

ssh -f -N proxy
<type password for your account, if required>

Please note that you need to open proxy connection every time you change network or disconnect/connect from network

Now you can clone and push over ssh proxy to gitorious.org, test as follows:

git clone git://gitorious.org/meego-quality-assurance/handset-ux-tests.git

How to use gitorious to do a merge request

There are as many ways to do a merge request as there are coders, so this guide just aims at helping at the beginning.

Register on gitorious

Go to https://secure.gitorious.org/users/new to create an account.

Then define a SSH (secure shell) key to enable secured communication between your Linux PC and gitorious. Tap below commands to generate such a key from Linux:

$ ssh-keygen
Follow your terminal instructions.
$ cat ~/.ssh/id_rsa.pub

Copy the result of "cat" command.
Then go to your user space on gitorious (example: https://gitorious.org/~heliaco), choose "Dashboard > SSH Keys > Add SSH Key", paste your clipboard's content, and save your update.

Make a personal clone of a gitorious repository

Go to the main page of the project you want to contibute to (example: https://meego.gitorious.org/meego-quality-assurance/auto-ux-testlib).
Click "Clone repository" button, change your clone name as you wish, and confirm your action.

Now you should see the SSH url of your clone which is like the following example: git@gitorious.org:~heliaco/meego-quality-assurance/heliaco-auto-ux-testlib.git.

Set up your Linux's working environment

From your Linux PC, clone the repository you just made:

$ git clone git@gitorious.org:~<username>/<project group>/<your clone name>.git
Example: git clone git@gitorious.org:~heliaco/meego-quality-assurance/heliaco-auto-ux-testlib.git

You need to define a name and email within git. For this you can either use a global .gitconfig file or specify these settings within a particular repository.

To create a global file, tap below command:

$ gedit ~/.gitconfig

Then add below section into it, mentioning your name and email:

[user]
 name = <Your name>
 email = <Your email>

Finally, save and close the file.

To configure name and email within a repository, tap below commands:

$ git config user.name "Your Name"
$ git config user.email "Your email"

Now, one possible way of working is to make development on a master branch, and use another branch called "upstream" in the process of merging requests.

To create a branch called "upstream", tap below command:

$ git checkout -b upstream

Then define the remote server path for "upstream" branch:

$ git remote add upstream git://gitorious.org/${project_group}/${project_name}.git
Example: git remote add upstream git://gitorious.org/meego-quality-assurance/auto-ux-testlib.git

And switch back to "master" branch:

$ git checkout master

Commit patches

In order to track the files you modified and/or added in the project, tap below command:

$ git add <modified and/or added files names>

Commit your patch using below command:

$ git commit
-m parameter allows you to comment your patch.

Then you have to sync the "upstream" and "master" branches.

Switch to "upstream" branch:

$ git checkout upstream

Update "upstream" branch:

$ git pull upstream master

Switch back to "master" branch:

$ git checkout master

Merge your "master" changes into the "upstream" branch:

$ git rebase upstream

Prior to push your patch, you can display your changes which are now in the "upstream" branch:

$ git diff upstream

Then, update the remote branch:

$ git push origin master

Perform a "merge request" from gitorious web UI

Go to http://meego.gitorious.org/~<username>/<project group>/<your clone name> (Example: https://meego.gitorious.org/~heliaco/meego-quality-assurance/heliaco-auto-ux-testlib).

Click "Request merge" button in the right column.
"Create a merge request" window appears, fill in "Summary" and "Description" fields, set your project name as "Target Repository" and select your commit(s).
Finally, click "Create merge request" button at the bottom of the page.