DGtal  1.5.beta
Git/Github source code management in DGtal

Table of Contents

Author
David Coeurjolly

This part of the manual describes how the DGtal Git repository is used on github and gives a couple of details on the git system.

Setting up your account and working copy

Create an account on github.com

  • go to github.com, then Signup -> Free account for opensource projects.
  • choose login/password and it's done
  • once it's ok, you're transferred to your "dashboard" with three options "Set up Git", "Create a Repo", "Fork a Repo" and "Be Social"
  • Select the first one.

Set up git

Github documentation is quite straightforward (see help/set up git in the Github web site).

In order to be to establish a secure connection between your computer and github servers and to be able to "push" changes to github servers, two methods are available: the SSH method or the HTTPS method, which is now recommended.

Note that in the HTTPS method, URLs look like "https://github.com/yourlogin/DGtal.git", whereas in the SSH method URLs look like "git@github.com:yourlogin/DGtal.git". The HTTPS method is used below.

In the meantime, you can also update your account settings (https://github.com/account)

Fork DGtal

Before going into details on git and git-commands, let's fork the initial DGtal repository. So, once you're logged in on github

Normal workflow

Set remote repositories and get a local copy

Once you have fork the initial DGtal repository, you can clone your fork to have a local copy of your own (remote) copy of DGtal:

git clone https://github.com/yourlogin/DGtal.git

In order to easily access to the initial DGtal repository, you can set it as a remote repository, called "upstream":

git remote add upstream https://github.com/DGtal-team/DGtal.git
add
ch add(Point(102.2, 50.2))

Git remotes are great because they allows to have multiple pull/push repositories. You can see the list of your remote repositories:

git remote
git remote -v

At this point, you should have two remote repositories:

  • origin, your own copy of the initial DGtal repository.
  • upstream, the remote repository you have just added containing the initial DGtal repository.

You can see the state of a remote repository called "remotename" with the command "git remote show":

git remote show remotename

In the normal workflow, you can pull from the main DGtal repository (upstream)...

git pull upstream master

...but only push to your own copy of DGtal (origin).

git push origin yourbranch

The merge between the two repositories is done by another developper after a pull request. To make a pull request, go to http://github.com/yourlogin/DGtal, click on "Pull Request". Then, choose the two branches you would like to merge (master in upstream and yourbranch in origin), write your comments and click on "Send Pull Request".

Edit files and commit in branches

0- Before starting to work, pull the upstream (you have to be online).

git pull upstream master

1- By default, you have a main local branch called master. Create a local branch "cool-feature".

git branch cool-feature

Note that you can see the list of your local branches:

git branch

Note also that the branch marked with a star is your current local branch. At this point you should see

- * master
- cool-feature

2- Jump onto your new local branch:

git checkout cool-feature

After taping the command "git branch" you should see now:

- master
- * cool-feature

3- Add files, edit files, commit local branch

git add newFile
git commit -a -m "This commit concerns the cool-feature in newFile ..."

Note that you can use the command "git status" or "git log" to have useful infos about the current branch state and the commits history.

4- Push to your fork (you have to be online)

git push origin cool-feature

This creates a new branch in your remote copy of DGtal, which is called "cool-feature", like your local branch.

But this is a shortcut to:

git push origin cool-feature:cool-feature

You can thus give a different name for your remote branch as follows:

git push origin cool-feature:another-name

5- If you have to work on another issue (e.g. bug #42), you can create a new local branch "bug42" from your master, jump onto it, commit edits, and push:

git checkout master
git branch bug42
git checkout bug42
git commit -a -m "Bug #42 fixed....."
git push origin bug42

6- Once you have finished to work on an issue, go to http://github.com/yourlogin/DGtal and ask for a "Pull Request"

7- Once the "Pull Request" has been validate and the merge done, you can remove your local branch:

git checkout master
git branch -d cool-feature

And you can also remove the associated remote branch (because everything should be merged into either the "master" of your fork, or the "master" of DGtal-team):

git push origin :cool-feature

Useful git commands

In this section, we detail couple of useful git commands.

git stash

Let suppose you have edited some files and that you figure out that these modifications should be in another branch (or you figure out that your are working on the wrong branch). The command

git stash

will put all your edits (uncommited edits) into a patch stack (and remove them from your working copy). Then, you can create your new local branch and "pop" your edit from the stack to reapply the changes. E.g.:

git pull //up-to-date branch "master"
//...
//edits
//...
//well... these edits should be in a separate branch!
git stash
git branch newLocalBranch
git checkout newLocalBranch
git stash pop
//...
//edits
git commit -a -m "...." //commit to new branch

To cleanup your stack: "git stash clear"

Note
In the previous example, it wouldn't have been possible to create/checkout a new branch since your current branch contained uncommited edits.

git Tracking Branches

Tracking branches are directely associated to a remote branch. On tracked branch you can directely apply push and pull with no other argument. After a clone the resulting origin branch is a tracking branch.

git checkout --track aRemote/aBranch

Then you will work on the new tracked branch aBranch

Note
the option –track work only from git version 1.6.2 and later. But you can perform equivalent with the following command:
git checkout -b [myBranchName] [aRemoteName]/[aBranch]

git Deleting a remote Branch

After working on your remote branch you can remove it from your server by using this particular syntax:

git push aRemoteName :theBranchToDelete

Basic comparison SVN/GIT

Clone == Checkout

svn checkout https://liris.cnrs.fr/dgtal/trunk
<==>
git clone git@github.com:DGtal-team/DGtal
or
git clone https://DGtal-team@github.com/DGtal-team/DGtal
DGtal
DGtal is the top-level namespace which contains all DGtal functions and types.

the clone will "clone" the repository with all its branches (default one "master" <==> "trunk" in SVN)

Update, Edit, add, commit, push

  • Fetch the changes from the server
    svn update <==> git pull
  • add a file into the VC system:
    svn add file <==> git add file
  • See the current status of your working copy
    svn status <==> git status
  • commit locally your changes (git only)
    git commit (commit the added files)
    git commit -a (commit the added files and the modified files)
  • push the modifications to the server (in the git case, you'll push all your local commits)
    svn commit <==> git push
  • create a branch
    svn copy URL URL (server side branch, you need to be online)
    <==>
    git branch toto (offline local branch)
  • Jump to another branch
    svn switch URL (server-side branch...)
    <==>
    git checkout toto (offline branch)
  • merge branches
    svn merge URL (assuming your WC is trunk)
    svn commit...
    <==>
    git checkout master (we go back to the "trunk")
    git merge toto (merger toto->trunk)
    git commit -a ...

Resolving GIT conflict (uncommon)

Even it is very rare, conflit can appear when you try to apply a pull:

>git pull upstream master
remote: Counting objects: 1, done.
remote: Total 1 (delta 0), reused 1 (delta 0)
Unpacking objects: 100% (1/1), done.
From github.com:DGtal-team/DGtal
branch master -> FETCH_HEAD
Auto-merging doc/cellular-topology.dox
CONFLICT (content): Merge conflict in doc/cellular-topology.dox
Auto-merging src/DGtal/topology/KhalimskySpaceND.ih
Automatic merge failed; fix conflicts and then commit the result.

To resolve the conflict you just have to apply the command:

> git mergetool

It will lunch simple tools like opendiff on MacOSX allowing to select the main file. After saving the merged file, you simply have to commit the new change:

> git commit -m "Merging GIT conflict! " -a
> git pull upstream master

For further details, there exist plenty of git tutorials on the web. I strongly encourage you to have a look to the progit.org one (http://progit.org/book/).

GitRef is also very nice: http://gitref.org/index.html

Important things:

  • git branches are local (but we can publish a branch too)
  • easy merge
  • except pull/push, everything else can be done offline (with a consistent history).