What follows is a general discussion on the normal workflow for CIlib. the usage of the tools, however, is a whole topic on it's own. We suggest having a look at the following references:
The tutorials are very good, especially Everyday Git. Also have a look at the Git Community Book.
Get the software :) Depending on whether you are using Linux, Mac or Windows, the installation instructions will vary.
Please consult your Linux distribution for information on how to install Git. Examples:
apt-get install git-core git-emailemerge git (useful to have the tcl
useflag enabled to get gitk installed)yum install gitIf you are on Mac or Windows, have a look at The Github Guides for more information on how to install the software..
We need to tell Git who you are exactly:
git config --global user.name "My Name"
git config --global user.email "myemail@example.com"
If you aren't on Unix, or you are not going tuse sendmail as your mail trnasfer agent, you will need to configure a connection to an SMTP server:
git config --global sendemail.smtpserver smtp.example.com
If the SMTP server needs you perform a login to send email:
git config --global sendemail.smtpuser "myusername"
git config --global sendemail.smtppass "myPassWord"
You obviously need to get the repository cloned:
git clone git://github.com/gpampara/cilib.git
Bear in mind that you may also use the http transport
instead of the git transport to get the repository
cloned - this is quite useful if you are behind a firewall.
Branch. It's good for you!
Seriously though, creating a local branch allows you to continue make changes to the source tree, compare with other branches and allows the creation of patches:
git branch fix_something
or
git checkout -b fix_something master
Switching to a branch is just as simple:
git checkout fix_something
Once you are in your local branch, you can go ahead and create changes to the code and commit them. Unlike SVN or CVS, the commits that are made will be associated with the current branch, and not with the upstream branch.
It's important to make sure that once you commit, you create a detailed description about what the changes involved or resulted in. Have a look at this to get an idea of what the commit message should include. Please note that detailed messages will be expected to get your commits applied to the main branch.
Git requires a two phase action to commit changes. Firstly you
will need to add / delete files to get them into the
index. After which you can commit them:
git add path/to/file
git delete path/to/file
git commit
To rename a file, request Git to do it for you:
git mv oldfilename newfilename
Deleting files from the repository is a similar command:
git rm <filename>
Now that you have completed the tasks you wanted to complete, you might like to submit the changes as a patch so that the rest of the community may benefit from your efforts. To send a patch requires a few small actions, the most notable being that we need to base the patch off the most recent version in the central repository. So, switch to the master branch and update it:
git checkout master
git pull
Next, we switch to the local branch and let git apply all our local changes on top of the renewed master that we just pulled:
git checkout fix_something
git rebase master
Finally, create the patch. A file with the name derived from he commit message will be created:
git format-patch -M -C master
All patches should be emailed to the CIlib developers mailing list, so that they can be discussed and finally agreed upon to be included in the master branch.
A very good resource on this topic is this document in the Git distribution.
While you are busy with your changes, the upstream repository may have advanced. You will want to get the upstream changes into your local repository.
You would switch to the master branch, then pull or fetch and finally update your patches to be based on the new upstream repository.
git checkout master
git pull origin
git checkout current_local_branch
git rebase master
The rebase can of course also be applied against the origin.
Adding coloring to your terminal is genarally rather useful, you can add that with: (or only a few of these)
git config --global color.branch auto
git config --global color.diff auto
git config --global color.interactive auto
git config --global color.status auto
git config --global color.pager false