This tutorial is based on Pro Git book, written by Scott Chacon, licensed under the Creative Commons Attribution Non Commercial Share Alike 3.0 license.
sudo apt-get install git
Configure your user and email for Git via the following command.
# Configure the user which will be used by git # Provide your full name git config --global user.name "Example Surname" # Same for the email address git config --global user.email "your.email@gmail.com"
Our two main branches are:
master stable
The master branch is used to our development, while stable branch should be in a state that allow a release at any time.
In a distributed version control system everyone has a complete copy of the source code (including the complete history of the source code) and can perform version control operations against this local copy.
Git performs commits to your local repository and you can synchronize your repository with other (remote) repositories. Git allows you to clone repositories, e.g. create an exact copy of a repository including the complete history of the source code. The owners of repositories can synchronize changes via push (transferring changes to a remote repository) or pull (getting changes from a remote repository).
In oofem project, everyone can clone the reference repository at oofem.org. If you want to contribute to the project, you make your development in your local repository. Then send your contribution to one of the lieutenants, responsible for merging the developers’ topic branches into the develop branch of reference repository. For more details on how to contribute follow Contributing to OOFEM.
If you want to get a copy of an existing Git repository — for example, a project you’d like to contribute to — the command you need is git clone.
$ git clone https://github.com/oofem/oofem.git
If you modify a file and you want to persist this change in the repository you need to perform two steps. First you need to mark them to be relevant for Git. Afterwards you add this change to the Git repository.
Marking changes as relevant for the version control is called staging or to add them to the index. Adding the changes to the repository is called committing.
For example, if you make a change in a file and want that this change is relevant for the next commit, you have to add the file to the via the
git add file
To commit marked changes into your local Git repository, use git commit command
git commit -m "your commit message"
The commit does not go to a remote server (oofem.org) - this is the major difference with svn.
The main command you use to determine which files are in which state is the git status command. If you run this command, you should see something like this:
$ git status # On branch master # Changes to be committed: # (use "git reset HEAD <file>..." to unstage) # # new file: README # # Changed but not updated: # (use "git add <file>..." to update what will be committed) # # modified: benchmarks.rb #
When the staging area is set up, you can commit your changes to local repository. Please note, that anything that is still unstaged — any files you have created or modified won’t go into this commit. They will stay as modified files on your disk. The simplest way to commit is to type git commit:
$ git commit
This will launches the editor, allowing you to enter your commit message. Alternatively, you can type your commit message inline with the commit command by specifying it after a -m flag, like this:
$ git commit -m "Fixing benchmark test b1.in"
You can show the history of commits in the current branch using git log command
git log
Or, alternatively, you can use a nice graphical view of the changes
gitk --all
When a repository is cloned, git automatically creates a master branch that tracks origin/master. You can set up other tracking branches if you wish — ones that don’t track branches on origin and don’t track the master branch.
One can see all branches in the repository using git branch:
$ git branch * master
To track remote branch, for example the develop branch on origin, use
$ git checkout -b stable origin/stable
If you have Git version 1.6.2 or later, you can also use the –track shorthand:
$ git checkout --track origin/stable
You can switch between branches using git checkout <branchname>.
$ git checkout stable
If you now call git branch, you will see that a new branch named stable has been set up and is the active one:
$ git branch
master
* stable
To synchronize your work, you run
$ git pull origin
This command looks up which server origin is, fetches any data from it that you don’t yet have, and updates your local database, moving your origin/master pointer to its new, more up-to-date position. It merges files from remote server with your data. The command $ git fetch origin only downloads files without merging them.
For people without write permissions to the GitHub oofem repository, the preferred way is to create a pull requests to propose and collaborate on changes in repository. The changes are proposed in a separate branch.
You can read more about Creating a pull requests on GitHub help pages.
Typically, one have to create a fork, or copy, of the repository. Forks let you make changes to a project without affecting the original repository. You can fetch updates from or submit changes to the original repository using pull requests.
If you have write access to the repository, you can also create branch directly within oofem repository. This should be reserved only to agreed, long-term, project-wide branches. For day-to-day and personal development, the forks are recommended.
After you have created a pull request, you can ask a specific person to review the changes you've proposed. In OOFEM, these people ('lieutenants') are in charge of a specific subsystem of the project and they merge in all changes related to that subsystem and push them to the reference (blessed) repository that everyone can clone from again.
Before contributing, please make sure you have followed oofem coding conventions.