SCM

Git starter guide

From Forge Wiki

Jump to: navigation, search

Git is a free and open source distributed version control system (VCS) designed to handle everything from small to very large projects with speed and efficiency.
Git is easy to learn and has a tiny footprint with lightning fast performance. It outclasses SCM (Source Code Management) tools like Subversion, CVS, Perforce, and ClearCase with features like cheap local branching, convenient staging areas, and multiple workflows.

The CamiTK team is now using git for the open source SDK developments. Please refer to the Git branching model explanation to understand the background idea of our branching model.

This page will guide you through a simple process from cloning repository to the share of your own work on it. Two approaches are described:

For those who are familiar with git, just a little warning: in the chosen git workflow, all development have to be made on the develop branch. Pushing to master is only possible for release or hotfix and is prohibited otherwise. You need to clone the master branch to always have the updated stable release. Switch to develop if you want the cutting edge version or if you want to contribute. Please create specific feature branches and push to develop once it is ready (see also Git branching model explanation).

Contents

Windows

On Windows platform, this page shows you a way to do things with Tortoise Git an explorer-integrated git client and is nicely built.

You also need to install Git for Windows in order for tortoisegit to work properly and / or to use Git from a command line, thanks to a linux-like bash. Installing Git for Windows is also recommended for developers as it allows CamiTK to retrieve more information for debugging.

There is a lot of other available tools to perform Git tasks, have a look here.

Basic usage

Get a local working directory

To work with Git for the first time, you should create a directory on your computer to clone the CamiTK referential, inside :

File:tortoiseGitClone.png


Put the correct URL. For example : https://forge.imag.fr/anonscm/git/camitk/camitk.git

File:tortoiseGitCloneUrl.png


File:tortoiseGitCloneResult.png


After this operation the CamiTK source code tree is download in your directory with all the VCS information. Becareful: by default you are on the master branch, and developers can only work on the "develop" branch (the master branch is kept for release and hotfix). Therefore, you have to switch from the master branch to develop branch.

Switching from master to develop branch

In the Tortoise contextual menu, select "switch/checkout..." command.


File:checkoutGitMenu.png


File:checkoutGitIHM.png

Select "origin/develop" branch, check the option "Create New Branch" with the name set as "develop", make sure that the "track" option is on, and click OK.


File:checkoutGitResult.png


You are now on your local copy of the develop branch which is tracking the remote one.

Create a feature Branch

As it is explain in CamiTK Git Branching Model developers work on a specific branch on their local repository, the "feature-xxx" branch (replace xxx with the short name of what you are expecting to accomplish). This branch is created by and for the developer her/himself. It can contain as many commit as needed. Once she/he is happy with the modification, she/he merges back to the local develop branch, and, then, push the result to the CamiTk Git repository. To create a new local/feature branch, follow the instructions below :

In the Tortoise contextual menu select "switch/checkout..." command.


File:checkoutGitMenu.png


File:NewBranchTortoise.jpg

Select "develop" branch, check "Create New Branch" with the name set as "feature-", this branch doesn't need to be tracked.


File:NewBranchResultTortoise.jpg


You can check if you are on the feature branch you have just created by watching the Windows contextual menu on your directory.


File:BranchingAwarness.jpg


You are now ready to work with your local copy!

Working with Git on your local copy

While your work is in progress, you may want to commit your work to register steps for instance. You can perform these operations at any time you want. You have a complete VCS on your own computer, so play with it. To do so follow these few tasks (Right click on the root directory of your working copy) :

Adding files and changes to the local Git index : Select the "add" item in the Git contextual menu. And select all the files you want to version.


File:AddContextMenuTortoise.jpg

File:AddFilesToGitDialogBox.jpg

File:AddResultDialogBox.jpg


commit : Select the commit item in the Tortoise Git contextual menu.


File:CommitItemTortoise.jpg


Check if everything is good and, as in any other VCS, give a meaningful commit message by following these guidelines.


File:CommitDialogBoxTortoise.jpg

File:CommitResultTortoise.jpg


You can perform these operations every time you have got something new. If you change something that already exists just do a commit. Consider a commit as a set of changes link together, as a little step toward the feature.

Sending your work over the CamiTK remote repository

Once your work is done you may want to push it on the remote repository to share it with the whole community.

Switch from feature branch to develop one : The first thing you should perform is to switch from your feature branch to the local develop one.


File:SwitchFromFeatureToDevelopTortoise.jpgFile:switchFromFeatureToDevelopTortoiseResult.jpg


Pull origin develop : After that, don't forget to pull from origin develop branch, to synchronize your local VCS.


File:pullContextMenuTortoise.jpg

File:pullDialogFromOriginDevelopTortoise.jpgFile:pullDialogFromOriginDevelopTortoiseResult.jpg


Merge from feature branch to develop one : When these preliminary operations are done you can merge your branch with the develop branch, so select merge in the Windows context menu. Be sure to check the "No Fast Forward" option.


File:mergeContextMenuTortoise.jpg

File:mergeTaskFromFeatureToDevelopTortoise.jpgFile:mergeTaskFromFeatureToDevelopTortoiseResult.jpg


Push to origin/develop : Finally, you can push your changes. Select push from the Windows contextual menu. You will get a new dialog which is similar to this one.


File:pushDevelopToOriginDevelopTortoise.jpg


Mac

You can use a GUI tool to perform tasks as it is described in the Windows part or directly the shell command line as it is described in the Linux part.

Linux

Install

On debian based Linux, simply type the following command:

sudo apt-get install git

For a GUI usage of Git you can install qgit or git-cola

apt-get install qgit
apt-get install git-cola

You can also use the KDevelop integrated git plugin.

Basic usage

Get a local working directory

To work with Git for the first time, you should create a directory on your computer to clone the CamiTK referential, inside. Execute the git clone command with the correct path to the remote repository you want to reach. See this page for more information about the URL to the CamiTK Git

$ mkdir src
$ git clone <remoteRepositoryURL> src # For example : git clone -b develop --single-branch https://forge.imag.fr/anonscm/git/camitk/camitk.git src

After this operation you get the CamiTK source code tree in your src directory, as well as all the VCS information, and you are on the master branch. Be careful: if you cloned using a developer's name, by default you are on the master branch, and developers can only work on the "develop" branch (the master branch is kept for release and hotfix). Therefore, you have to switch from the master branch to develop branch. If you cloned only the single branch develop, you don't need to switch to the develop branch, it is already the default branch.

Switching from master to develop branch

To perform these commands you have to be located in the src directory. The second thing to do is to create the branch named develop, which will available locally as a copy of the origin version (origin/develop). So here we go:

$ cd src
$ git checkout -b develop origin/develop

You are now working on your local copy of the develop branch which is tracking the remote one. If you get an error "A branch named 'develop' already exists.",, don't worry, this means you are already working in the develop branch.

Checking the current branch

If you type:

$ git branch

You should at least see on line "develop" marked with a star (the current branch).


Create a feature Branch

As it is explain in CamiTK Git Branching Model, developers work on a specific branch on their local repository, the "feature-xxx" branch (replace xxx with the short name of what you are expecting to accomplish). This branch is created by and for the developer her/himself. It can contain as many commit as needed. Once she/he is happy with the modification, she/he merges back to the local develop branch, and, then, push the result to the CamiTk Git repository. To create a new local/feature branch, follow the instructions below :

$ git branch feature-f1
$ git checkout feature-f1

Note: f1 should be a comprehensive small name of the work you intend to do.

You are now ready to work with your local copy!

Working with Git on your local copy

While your work is in progress, you may want to commit your work to register steps for instance. You can perform these operations at any time you want. You have a complete VCS on your own computer, so play with it. To do so follow these few tasks (Right click on the root directory of your working copy):

Adding files and changes to the local Git index (staging)

$ git add .  # to add files
$ git status # to get informations about the current state

commit

Check if everything is good and, as in any other VCS, give a meaningful commit message by following these guidelines.

$ git commit -m "commitMessage"

You can perform these operations every time you have got something new. If you change something that already exists just do a commit. Consider a commit as a set of changes link together, as a little step toward the feature.

Sending your work over the CamiTK remote repository

Once your work is done you may want to push it on the remote repository to share it with the whole community.

Switch from feature to develop

The first thing you should perform is to switch from your feature branch to the local develop one.

$ git checkout develop

Pull origin develop

After that, don't forget to pull from origin develop branch, to synchronize your local VCS.

$ git pull origin develop

Merge from feature to develop

When these preliminary operations are done you can merge your branch with the develop branch, so select merge in the Windows context menu. Be sure to add the "No Fast Forward" (--no-ff) option.

$ git merge --no-ff feature-f1

Push to origin/develop

Finally, you can push your changes.

$ git push origin develop

You can check on the CamiTK git develop branch web page that your branch was merged. Don't forget to follow the continuous integration result.

Powered By FusionForge