Git

From GDCM Wiki
Jump to: navigation, search

GDCM version tracking and development is hosted by Git.

Contents

Official Repository

One may browse the repository online using the web interface at http://sourceforge.net/p/gdcm/gdcm/ci/master/tree/.

Cloning

These instructions assume a command prompt is available with git in the path.

Clone GDCM using the command (read-only)

$ git clone git://git.code.sf.net/p/gdcm/gdcm

if you are a developer on GDCM, prefer:

$ git clone ssh://username_sf@git.code.sf.net/p/gdcm/gdcm

Ref

If you want to run tests, add the --recursive option to download the Testing/Data submodule.

$ git clone --recursive git://git.code.sf.net/p/gdcm/gdcm

This requires Git 1.6.5 or higher.

All further commands work inside the local copy of the repository created by the clone:

$ cd gdcm

If you already cloned and want to add the Testing/Data submodule then run

$ git submodule update --init

HTTP GIT

If you are behind a firewall, you can now (since the recent switch to allura 17/12/2012) do:

$ git clone http://git.code.sf.net/p/gdcm/gdcm

GITHUB MIRROR (deprecated)

$ git clone git://github.com/malaterre/GDCM.git

Pay attention that this mirror is updated every 24h. Since the machine doing the mirroring is down, this is deprecated. Sorry.

See:

Updating

If you have made no local commits and simply want to update your clone with the latest changes, run

$ git pull
$ git submodule update

If you know you do not have the Testing/Data submodule checked out then you can skip the submodule update command.

Branches

At the time of this writing the repository has the following branches:

  • master: Development (default)
  • release: Release maintenance
  • hooks: Local commit hooks (to be placed in .git/hooks)
  • dashboard: Dashboard script

Release branches converted from SVN have been artificially merged into master. Actual releases have tags named by the release version number.

After cloning your local repository will be configured to follow the upstream master branch by default. One may create a local branch to track another upstream branch using git checkout:

$ git checkout -b release origin/release

or directly:

$ git clone -b release git://git.code.sf.net/p/gdcm/gdcm

gitweb

The git repository can be viewed online:

Development

GDCM development uses a branchy workflow based on topic branches. Currently we use a single master integration branch for development and one release branch for release maintenance.

Workflow

Our collaboration workflow consists of three main steps:

  1. Create Topics
  2. Share Topics
  3. Integrate Topics

Introduction

These steps are a one-time setup per-user per-machine.

We require all commits in GDCM to record valid author/committer name and email information (You need an actual sf.net account) Use git config to introduce yourself to Git:

$ git config --global user.name "Your Name"
$ git config --global user.email "you@users.sf.net"

Note that "Your Name" is your real name (e.g. "John Doe", not "jdoe"). While you're at it, optionally enable color output from Git commands:

$ git config --global color.ui auto

If less displays strange characters and no color, your LESS environment variable may already be set. You can override the less options with:

$ git config --global core.pager "less -FXRS"

The --global option stores the configuration settings in ~/.gitconfig in your home directory so that they apply to all repositories.

Hooks

This step should be done once for each local clone of the GDCM repository.

$ cd gdcm
$ cd .git/hooks
$ git init
$ git pull git://git.code.sf.net/p/gdcm/gdcm  hooks
$ cd ../..

Local Commits

Develop locally on a well-named topic branch:

$ git checkout -b my-cool-feature origin/master
$ edit files
$ git add files
$ git commit

Use the editor to enter a descriptive message (leave the message blank to abort the commit). Start with a one-line summary (suitable for use as an email subject line), then leave a blank line, then use free-form paragraph text to describe the change.

Patches

For limited contribution, it is recommended to use the patch approach. See Git/Patches

Pushing

Authorized developers may publish work directly to sf.net/gdcm.git using Git's SSH protocol.

Submodules

In the GDCM.git repository, Testing/Data is not really a directory. It is a submodule, meaning that its content does not actually appear in GDCM.git, but in the GDCMData.git repository. In GDCM.git Git stores in the Testing directory an entry called "Data" that refers to a commit from the GDCMData repository. Indeed, one can see this using a low-level "git ls-tree" command:

$ git ls-tree -r 9ec7c03d -- Testing/Data
160000 commit bc9550f3215104818f0464fd6ede7c8ea3462aeb  Testing/Data
              ^^^^^^^^

This approach allows us to keep the bulky data out of the main repository and version it separately. Every version of GDCM throughout history refers to the exact version of GDCMData that it needs using this submodule link.

Updating Data

One can think of the Testing/Data entry in GDCM's tree kind of like a file that tells Git which version of GDCMData.git we want. If we want to change the version of GDCMData.git to which we refer from GDCM (perhaps because we've created a new commit in GDCMData with some updated images), we commit a change to GDCM that updates the Testing/Data "file" to refer to the new version.

First, make the changes to GDCM needed to use the new data correctly:

$ git checkout -b my-new-test origin/master
$ git submodule update
$ edit files

Then, make the change to Testing/Data and publish it:

$ cd Testing/Data
$ git checkout master
$ git pull --rebase origin master
$ edit data-files
$ git add -- data-files
$ git commit
$ git push origin master
$ cd ../..

Finally, update GDCM to reference the new version of GDCMData. Our work tree already has the new version checked out in Testing/Data so we just need to tell Git to include this change in the next commit.

$ git add -- Testing/Data

The commit may also include the files edited above to use the new data:

$ git add -- files
$ git commit

Now publish the GDCM commits as you would any other topic.

Hacking socketxx

socketxx is a subtree, this is slightly different from a submodule. socketxx is released under a BSD-style license which is 100% compatible with GDCM.

It was pushed outside of GDCM for a cleaner design. Since socketxx is a subtree, there is absolutely no impact for the user. Having socketxx as a subtree only is an advantage for the developers to cleanly develop against socketxx and only socketxx. socketxx subtree will be merge as bugs or features are implemented.

Again socketxx being a subtree of gdcm has 0 impact for the user, simply clone your gdcm repository as you would do it in the past.

If you are a developer and wishes to develop a patch against socketxx simply do:

$ git clone ssh://username_sf@git.code.sf.net/p/gdcm/socketxx
[HACK HACK]
$ git push

and then update gdcm:

$ git clone git://git.code.sf.net/p/gdcm/gdcm
$ cd gdcm
$ git remote add socketxx git://git.code.sf.net/p/gdcm/socketxx
$ git pull -s subtree socketxx master

Testing

Dashboard

The dashboard branch contains a dashboard client helper script. Use these commands to track it:

$ mkdir -p ~/Dashboards/GDCMScripts
$ cd ~/Dashboards/GDCMScripts
$ git init
$ git remote add -t dashboard origin git://git.code.sf.net/p/gdcm/gdcm
$ git pull origin

The gdcm_common.cmake script contains setup instructions in its top comments. Update the dashboard branch to get the latest version of this script by simply running

$ git pull origin

For nightly machine, we are storing the ctest script used for the nightly builds directly in the git dashboard branch see online:

Ressources

sf.net

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox