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.
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 "firstname.lastname@example.org:yourlogin/DGtal.git". The HTTPS method is used below.
In the meantime, you can also update your account settings (https://github.com/account)
Before going into details on git and git-commands, let's fork the initial DGtal repository. So, once you're logged in on github
In order to easily access to the initial DGtal repository, you can set it as a remote repository, called "upstream":
Git remotes are great because they allows to have multiple pull/push repositories. You can see the list of your remote repositories:
At this point, you should have two remote repositories:
You can see the state of a remote repository called "remotename" with the command "git remote show":
In the normal workflow, you can pull from the main DGtal repository (upstream)...
...but only push to your own copy of DGtal (origin).
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".
0- Before starting to work, pull the upstream (you have to be online).
1- By default, you have a main local branch called master. Create a local branch "cool-feature".
Note that you can see the list of your local branches:
Note also that the branch marked with a star is your current local branch. At this point you should see
2- Jump onto your new local branch:
After taping the command "git branch" you should see now:
3- Add files, edit files, commit local branch
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)
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:
You can thus give a different name for your remote branch as follows:
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:
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:
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):
In this section, we detail couple of useful git commands.
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
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.:
To cleanup your stack: "git stash clear"
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.
Then you will work on the new tracked branch aBranch
After working on your remote branch you can remove it from your server by using this particular syntax:
the clone will "clone" the repository with all its branches (default one "master" <==> "trunk" in SVN)
Even it is very rare, conflit can appear when you try to apply a pull:
To resolve the conflict you just have to apply the command:
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:
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