User Tools

Site Tools


git-tutorial

This is an old revision of the document!


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.

Installing Git

  • Many Linux distributions provide packages for git, for example on Ubuntu you can install git by typing:
 sudo apt-get install git
  • Git for Windows is provided by the |msysgit project.
  • On Mac OS, the easiest way is to use the dmg packages provided by the Git for OS X project.

Setup

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" 

Git Basics - Just for Understanding

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.

Local and remote repositories

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.

Cloning oofem repository

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 http://www.oofem.org/git/oofem.git oofem.git

Staging Modified Files

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.

Viewing Your Staged and Unstaged Changes

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
 #

Committing Your Changes to Local Repository

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"

Viewing the Commit History

You can show the history of commits in the current branch using gil log command

  git log
  

Or, alternatively, you can use a nice graphical view of the changes

  gitk --all 
  

Working with remote branches

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.

Contributing to OOFEM - Practical Workflow

Contributing to oofem project is different. Typically, you don’t have the permissions to directly update branches on the project reference repository and you have to pass your contribution(s) to the maintainers in some way. 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. In general, lieutenants prefer to accept contributed patches via e-mail.

Before contributing, please make sure you have followed oofem coding conventions.

First, you’ll probably want to clone the main repository, create a featureA branch for the patch or patch series you’re planning to contribute, and do your work there. The sequence looks basically like this:

Clone reference repository from remote server. This creates only master branch in you local machine. 'oofem.git' is an arbitrary name of directory.

$ git clone http://www.oofem.org/git/oofem.git oofem.git
$ cd oofem.git

Note: when a repository is cloned, git automatically creates a master branch that tracks origin/master branch, but there is no automatic update (need to use “pull” command)

Normally, we do not want to modify master branch directly. For this reason, we create a new brach featureA for our development, which is a copy from an active previous branch master

$ git checkout -b featureA
$ (work)

Locally modified files need to be uploaded to local server. Use option -a to upload all changed files which were included in the local repository. A message required on commiting will go also to a remote server.

$ git commit -a
$ (work)
$ git commit -a

Now, while you are working hard on your new feature, other developers complete theirs and push their changes to the remote master branch. When you're done with your project, you need to first get the most recent version of the project's code. Change to the master and pull out the most recent remote version.

$ git checkout master
$ git pull --rebase

Now, to make merging your code easy, you should rebase your featureA. What this does is add all the commits you just pulled in to your featureA. Any conflicts that arise will happen in your featureA as well, leaving your master branch clean and in order.

$ git checkout featureA
$ git rebase master

:!: It is stronlgly recommended to use rebase -i to squash your work down to a single commit, or rearrange the work in the commits to make the patch easier for the maintainer to review — see Git book for more information about interactive rebasing.

Optionally, your branch can be merged into single master on a local machine and featureA can be deleted

$ git checkout master
$ git merge featureA
$ git branch -D featureA

Now you have your commits that you want to send to the maintainers. You use git format-patch to generate the mbox-formatted files that you can e-mail — it turns each commit into an e-mail message with the first line of the commit message as the subject and the rest of the message plus the patch that the commit introduces as the body.

$ git format-patch -M origin/master
0001-add-limit-to-log-function.patch
0002-changed-log-output-to-30-from-25.patch

The format-patch command prints out the names of the patch files it creates. The -M switch tells Git to look for renames. To e-mail this to a maintainers, you can either paste the file into your e-mail program or send it via a command-line program.

For those, who have write access to remote server, the local repository can be uploaded to remote server. Without any options, all branches, where local_name=remote_name will be pushed

$ git push

To be sure pushing only master branch, use

$ git push origin master

Maintainers

FIXME Here it would be nice to mention all lieutenants, with their e-mails. But perhaps better solution would be to create a mailing list, where the patches could be send (this will hide the individual e-mails). Then the work has to be distributed somehow …. Any ideas?

Links

git-tutorial.1355692477.txt.gz · Last modified: 2012/12/16 22:14 by smilauer