Using Git with codeBeamer

Tags: Git Version Control System

Using Git with codeBeamer

Git Overview

Git is a free & open source, distributed version control system designed to handle everything from small to very large projects (e.g. Android) with speed and efficiency. Every Git clone is a full-fledged repository with complete history and full revision tracking capabilities, not dependent on network access or a central server. Branching and merging are fast and easy to do.

Installing codeBeamer with Git

The installation takes only a few steps:

On Linux you can use the package manager to install Git. The package name for Ubuntu and RedHat is git-all (or git depending on the distribution version).
On Windows (since 6.0.3) Git is shipped with codeBeamer and can be used with Smart-Http out of box.

Install codeBeamer
Start codeBeamer

After installing Git and codeBeamer configure access to the Git repositories. See URLs of Managed Git Repositories for details.

Using Git in Eclipse IDE with EGit plugin

The EGit

plugin is a good, simple tool to integrate Git into the Eclipse IDE. It can be easily installed using Eclipse's Help→Software updates feature to add the EGit update site

(This link only works in Eclipse). Limited documentation is also available on the project wiki

Learn more about using Git with codeBeamer in the Eclipse IDE in this page.

URLs of Managed Git Repositories

There are three ways to access a local managed repository from remote clients:

Smart HTTP access (read-write) - easiest to use.
SSH access (read-write).
Git daemon read-only access (without permission check).

Smart HTTP

This kind of URL is a simple HTTP URL that can be used for push and pull operations too. For example:

http://akostajti@localhost:8080/cb/git/myrepositoryname

All type of URLs can include a password. For example:

http://akostajti:secret@localhost:8080/cb/git/myrepositoryname

If you specify your password in the URL you don't have to always type it in the command line. Since 6.0.3 passwords can be provided also in MD5 format instead of plain-text.

SSH Access

This works out of the box, but the OpenSSH server must be installed on the machine where codeBeamer runs. Please check the availability of a version which is fit for your Linux distribution, or check out the official site. When the OpenSSH package is installed and configured (automatic configuration is enough), codeBeamer must be restarted, and the rest is managed by the server itself. Project members must upload their keys according to Setting Up SSH Authentication for Git and Mercurial.

Public Access with git Daemon

This is a simple sharing capability which is part of the Git core package, and allows unauthenticated read-only access to a repository. codeBeamer controls the daemon start/stop. This is available by default in the CB server on Linux platforms. The port of this service is 9418 (Git default) which can be configured in general.xml:

<scc>
   <git>
     <daemon start="true" port="9418" />
   </git>

For example:

git://localhost:9418/myrepositoryname

How to Use Git with codeBeamer

The following sections explain how to set up and use a Managed Git Repository in codeBeamer. The codeBeamer terminology distinguishes between "managed" and "external" repositories. For more information, see this wiki's parent Using Managed Subversion, Git & Mercurial Repositories.

Setting Git User Name - Author (Step 1)

This user must match the username registered to codeBeamer, while the email address must match the registered email address in codeBeamer for that user. This allows the codeBeamer server to correctly associate the user's local commits (changes in the repository) to the codeBeamer user when pushing them to the server. codeBeamer tries to resolve the identity of the change, but if this fails the push will be rejected (even if the authentication was correct)

Configure your Git client to set author information on commits. The author must be the same as your codeBeamer username. Enter the following commands in the terminal (global git configuration):

git config --global user.name "my.codebeamer.username"
git config --global user.email "my@registered.codebeamer.address.com"

Cloning Repositories, Committing and Pushing Changes (Step 2)

Creating Managed Git Repositories follow the steps described in

Using Managed Subversion, Git & Mercurial Repositories.

We now need to get our copy of the source code so we can work on it. This is done by cloning the repository:

git clone http://account-name@codebeamer.server.name.or.ip:port/cb/git/your.repo.name

or using SSH

git clone ssh://codebeamer@codebeamer.server.name.or.ip/git/your.repo.name

After you have changed the files or fixed bugs, etc you are ready to commit your changes to the repository.

cd your.local.repository.dir
echo Hello > new.file.name
git add new.file.name
git commit -m "Commit message, added new file"

This will commit changes locally to your repository. Now send (push) your changes to remote (upstream) repository:

git push origin master

A push operation can send more than one commits to codeBeamer. Make your changes and repeat the steps above without the push. When you want to share your work, execute a 'git pull' to get the latest revisions and update (or merge) your local clone, and then execute 'git push'. That will send all the changes at once.

The files that you commit into git, and push to codeBeamer must be encoded using UTF-8.
Otherwise the system displays the diffs and file contents incorrectly.

Associating Issues with Commits (Step 3)

To associate an issue with a commit, first create an issue within a codeBeamer tracker. Remember or jot down the id-number of the generated issue, and start working on implementing/fixing source code in connection with it. When you are finished, open a terminal window and enter the following commands (replace "1234" with the ID of the issue you want to associate your commit with):

cd your.local.repository.dir
git commit -a -m "#1234 Fixing an NPE"

Use the issue ID you've created: this will commit changes locally to your repository. Now send your changes to codeBeamer:

git push origin master

Select your Project from context menu
Click on the SCM Repositories tool menu
Select the (upstream) repository

You can now see your commit(s) on top of the history, and the issue #1234 (check the link on the rightmost cell) is associated with your change. You can check the "back" association by clicking on this link, and see your change info on SCM Commits tab on the bottom.

For more information on associating issues with commits, please see Tracing Source Code Changes to Requirements, Task and Bugs.

Converting an Existing Git Repository to a Managed One

An unmanaged (external) repository can be converted to a managed one using bundles as described in Creating Managed Repositories.

Creating Bundles

When creating a managed respository you can use bundles. A bundle is a package of change sets. codeBeamer unbundles this package on the server and you can use that repository as if you cloned the original one.

To create a bundle from the contents of a repository you can use the git bundle command. For example the command (executed in a repository directory)

git bundle create dmp.bundle master branch-v1 HEAD

will create a bundle named dmp.bundle that contains the master and the branch-v1 branches. You can list the reference names acceptable by git bundle create using git show-refs. Please note that you must always include HEAD to be able to work with the bundle. Or use this form of the command