Brief introduction to Git

From Gramps
Revision as of 17:39, 24 November 2014 by Kulath (talk | contribs) (update external web-link)
Jump to: navigation, search

The development source code of Gramps is stored in the Git repository at SourceForge.

This helps synchronizing changes from various developers, tracking changes, managing releases, etc. If you are reading this, you probably want to do one of two things with Git: either download the latest source or the development version, or else upload your changes (if you have write access to the repository) or make a patchfile (if you don't have write access).

Install Git on your system

  • Debian/Ubuntu: sudo apt-get install git
  • Fedora: yum install git-core
  • Mac OS X (intel) Download git from here
  • Mac OS X (PPC) Although the git download above is called 'git-', implying that this is a universal binary, in fact only the installer is universal, the binary to be installed in actually intel only. On a PPC you will need to build git manually. Follow the instructions here: I think you will also need some additional tools like 'msgfmt'. I don't think this is installed by the Apple development tool Xcode, but fortunately I have it either via fink which I installed some time ago, or via MacPorts which I installed more recently.

Mac OS X (PPC) Eclipse. If you are using Eclipse on a PPC, then there may be missing components for installing the latest version of EGit, depending on your version of Eclipse. If you have the Helios version of Eclipse, then you will not be able to install the latest EGit because you will get requires ' 3.6.100' but it could not be found. Installing EGit version 2.0 from should work if you uncheck the EGit Import Support feature when selecting what to install. You will obviously lose the Import Support feature. See here. You will probably need to do git config core.filemode false to get round this bug as suggested here.

If you use Eclipse then will need to locally ignore the Eclipse files as suggested at 5.2.2 here.

cd ~/
touch .gitignore
echo ".metadata" >> .gitignore
echo ".project" >> .gitignore
echo ".pydevproject" >> .gitignore
echo "windows" >> .gitignore

Git includes your name and email address in commits. To configure them, use the following commands:

git config --global "John Smith"
git config --global [email protected]

Git will automatically convert line endings for you. Use the following settings:

git config --global core.autocrlf true  # Windows
git config --global core.autocrlf input  # Linux/Mac

Obtaining a copy of the Gramps repository

The description below is for a single working folder at ~/Gramps. An alternative approach for Multiple Working Folders is described below.

To obtain a copy of the Gramps repository, type the following in the command line if you don't have a sourceforge account:

git clone git:// Gramps

You should see the downloading progress reported in your terminal.

If you have a SourceForge account, use ssh instead:

git clone ssh://<username> Gramps

You will need a SSH Key in order to authenticate using this method. Before you accept any host keys, make sure you verify the fingerprint of

Basic Work Flow

The basic work flow after you've checked out the repository is update, develop, commit, update again, push. To update the current branch, run

git pull --rebase

As a general rule always use git pull --rebase to avoid creating unnecessary merge commits. Note that one must have no uncommitted edits when running git pull.

The differences between "git pull" and git pull --rebase" is explained well here.

To review your changes before a commit, type:

git status

To commit your changes locally, use the following command:

git commit

Which will bring up the default $EDITOR to create a commit message. If you are fixing a bug, the first line of the commit message should be the bug number and title, otherwise a brief statement of purpose. Skip a line and describe what you did.

If the commit is a minor change that can be described entirely in the subject, you can instead use:

git commit -am "message describing the nature of the change"

Try to keep your commits digestible and understandable. A large changeset can be broken into several commits that "tell a story" about how the changeset moves the program from its old behavior to its new one.

To push your changes to the Gramps repository, you need to have cloned the Gramps source code with ssh, and have push access to the Gramps repository (the Gramps admins can give you this, Brian Matherly or Benny Malengier). First update again to make sure that you can fast-forward the repository, then push:

git pull --rebase
git push

Since uploading is a potentially dangerous operation, most people do not obtain write access to the git repository. In this case, create a new bug on the bug tracker and attach a patch to it. See the make a patchfile section for details.

If someone else has made changes that interfere with yours, you will get a conflict error when you pull. You will have to resolve that conflict and re-commit (you can use git commit --amend if it affects only the last unpushed commit) before git will push successfully.

Also see: Getting started with Gramps Trunk.

Types of branches

When you clone the Gramps repository, a branch called master will be created for you. This contains the latest development version of Gramps. Gramps maintains different branches in several categories:

  • master - There is only one master branch. All new feature and most bug-fix development happens in the master branch. New releases never come from the master branch.
  • maintenance - There are many maintenance branches, though usually only one or two are active. A maintenance branch is created from the master branch when all the features for a release are complete. New features are not committed to maintenance branches. Releases only come from active maintenance branches; a branch is no longer active when no further releases are planned for it. Inactive branches should not have any changes committed to them. The purpose of maintenance branches is to allow the line of code to stabilize while new features are added in the master branch. In order to prevent regressions (fixed bugs reoccurring in later releases), it is a "best practice" to fix bugs on the master branch and then to backport them to the current maintenance branches.
  • geps - These are meant for development of Gramps Enhancement Proposals. Most of the time GEPS are developed in the master branch. Occassionally a GEP will require extensive reworking or long periods when the code base is ususable. In these cases a branch in geps can be used as a temporary development area. Once the hard work is done the change should be merged into the trunk and the geps branch should be removed. geps branches should follow the naming convention gep-<###>-<descriptive text> e.g. gep-013-server. Please read the #Working with development branches section for help with managing these branches.

Tags are created for each Gramps release. The first two digits of the Gramps version number are reserved to indicate the maintenance branch the code came from. The last digit indicates the revision from that maintenance branch. For example, 3.0.4 would indicate the 5th release from the 3.0 branch (3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4).

Here is a hypothetical example: Imagine that the current version of Gramps is 8.3.2. A new series of features has been added in the master branch and are ready for release. A new maintenance branch is created from the master branch named 8.4 (or possibly 9.0 depending on the nature of the new features). New features continue to be added in the master branch that will not be included in the 8.4 series of releases, but will be included in the 8.5 series. Bug fixes continue to occur in the 8.4 branch until the code is deemed worthy of release. At that time, a release is tagged from the 8.4 maintenance branch and named 8.4.0. Some time after the release of 8.4.0, some bugs are found and fixed in the 8.4 maintenance branch. Those bug fixes are released as 8.4.1.

Stable version

There are several versions of the Gramps source code in Git. The development branch for small changes and bug fixes is maintenance/gramps51.

By default, the remote server you cloned the Gramps repository from is called origin.

To see a list of branches on the server, type:

git remote show origin

To create a local branch which tracks a branch on the server, use:

git checkout -b gramps41 origin/maintenance/gramps41

This sets the name of the local branch to "gramps41" (not "maintenance/gramps41"). This may cause problems when you come to "push" your changes back to the server, depending on the "push.default" configuration settings (see below). You can change the name of the local branch by "git branch -m old new" i.e.

git branch -m gramps41 maintenance/gramps41

This is known as a "tracking" branch.

To list the available branches, type:

git branch

The current branch is marked by an asterisk.

To switch to another branch, type:

git checkout <branch>

To look at any stable release version, type:

git checkout <tag> -b <new_local_branch_name>

The following configuration option simplifies pushing a branch back to the server:

git config --global push.default upstream

You can then use:

git push

This will push commited changes from all local branches, not just the one that is currently checked-out. If you want to ensure that only one branch is pushed, then use:

git push origin gramps41:maintenance/gramps41

Where for bugs?

The bug tracker has in the right top angle different projects. Choose project trunk and submit an issue.

Making a patchfile

If you do not have push access to the repository, you can make a patchfile with your changes. This is a text file which can then be sent by email to somebody, or posted/uploaded to the bug tracker (against a bug you are fixing or a feature request which you are solving for instance), etc...

These instructions tell how to make a patchfile against the master branch, so that your changes are added to the next major release of Gramps. (To make a patchfile against a branch the process is similar, with some slight changes.)

First create a new branch to work in:

git checkout -b fix

Then use your favorite editor to change whatever file(s) you want. Add the files you have changed to the staging area and commit them.

Obtain the latest changes from the server.

git checkout master
git pull --rebase

Next, rebase your fix again the master branch. This will ensure that your patch will apply cleanly.

git rebase master fix

This will leave you in the fix branch.

Finally, create a patchfile, using:

git format-patch master --stdout > fix.patch

You now have a patchfile that can be sent by email, or attached to a bug report. The patch can be applied using the 'git apply' command.

Working with development branches

Creating branches with Git is quick and easy.

Here is a quick crib sheet:

Creating a branch

To create a branch from the master branch:

git checkout master
git branch gep-014-fab-feature

To make this branch available on the server use:

git push origin gep-014-fab-feature

Merging changes from the branch back into the master branch

When you are ready to merge your changes back into the master branch:

git checkout master
git merge gep-014-fab-feature
git push

Removing branches

It is important that branches are removed once they have been merged into the trunk or have been abandoned. To remove a branch:

git branch -d gep-014-fab-feature

To remove a branch from the server, use:

git push origin :gep-014-fab-feature

The developers reserve the right to remove branches that have been dormant for more than 1 year.

Applying a fix to another branch

If you write a fix for the master branch, you may need to also apply it to a maintenance branch.

To apply a commit from the a branch to a maintenance branch:

git checkout gramps41
git cherry-pick fix

Then you may have to fix things that could not be applied due to conflicts. The patch program would mark the conflicts with the <<<<<<, ======, and >>>>>> signs. You will then need to push your changes.

If you apply a small fix that applies cleanly to another branch, it can be done like this (assuming you've just committed the fix to master in a single commit):

git checkout gramps41
git diff master^ master | git apply

If `git apply' fails, nothing will be changed in the working copy, and you can try to resolve the conflicts by cherry-picking, or manually saving the diff result, using the "patch" program, and resolving the conflicts.


Before switching to another branch it is useful to remove untracked files created by the build process. You can do this with the following command:

git clean -dxf

Useful Tips

Getting help

Git has excellent man pages. You can view the manual page for a Git command, by using one of the following:

git help <verb>
git <verb> --help
man git-<verb>

For example, to get help on the 'git log' command, type:

git help log

Configuration settings

You can set your default editor with:

git config --global core.editor <editor>

To enable colored command line output, use:

git config --global color.ui auto

Some procedural recommendations

  1. Always do git pull --rebase before pushing changes to the server. If necessary get advice about handling conflicts.
  2. Always do git status and look for staged files that are unexpected or unintended. This is a *very important* sanity check.
And here are a couple of incidental suggestions
  • Avoid grouping unrelated changes; better to divide into separate commits for the following reasons: a better log entry; easier troubleshooting/reverting. (and probably more).
  • Similar to above, it may be better to make small incremental changes than one big one (if possible). Interim changes should not introduce breakage, of course. For instance, if you change code in gramps/ and do associated translation changes in po/, you might want to commit the changes in po/ in a commit following the commit(s) with the changes in gramps/.
  • logs are important -- please give some thought to the log message. All developers should read the Committing policies.

Multiple Working Folders

Using a single working folder as described above entails context switching when developing across multiple branches. For example:

  • develop and test changes on the gramps41 branch,
  • commit or stash the changes,
  • clean to remove untracked files created by the development process,
  • checkout the master 'branch',
  • build (python build),
  • cherry pick the changes from the gramps41 branch into the master 'branch',
  • test and if necessary develop the changes to master,
  • commit or stash the changes.

If the changes are all OK, then they can pushed to the SourceForge repository.

An alternative is to clone the SourceForge repository for each branch, but although git saves local disk space by using hard links for locally cloned repositories, keeping the local repositories in sync is complex.

The problem is well explained here as is the solution, which is to create copies of the working directories only. This is done by a script that is in the git 'contrib' directory git-new-workdir.

Assuming that the directory structure would be:

      +- etc

The approach would be:

  • checkout from the SourceForge repository (it doesn't much matter which branch you checkout as we are not going to use this branch directly):
git checkout -b Gramps/repository origin/master
  • then create the various working copies:
git-new-workdir Gramps/repository ~/Gramps/gramps34 maintenance/gramps34
git-new-workdir Gramps/repository ~/Gramps/gramps40 maintenance/gramps40
git-new-workdir Gramps/repository ~/Gramps/gramps41 maintenance/gramps41
git-new-workdir Gramps/repository ~/Gramps/master master

You will then need to build the source, but this only needs to be done once, and the 'clean' step is not needed. See Run from source and running which describes the process for 'gramps 3.4 and before' as well as after. For example:

cd ~/Gramps/gramps41
python build

Browse Git

An alternative to the command line tools to view the Git repository is the online interface.

Send your contribution without rights to push

Check it into Git if you obtained the permission to do push. Otherwise you can fork gramps repository with a SourceForge account and pull a merge request.


The Gramps project does not keep a ChangeLog file under source control. All change history is captured by git automatically when it is committed. A ChangeLog file is generated from the git commit logs before each release using git2cl. Developers should take care to make useful commit log messages when committing changes to git. Please read the Committing policies for details.

How to use git2cl

Starting with Gramps 3.0.0, we no longer have a ChangeLog file.

Instead, the list of changes is generated automatically using the standard git2cl script.

Note that git2cl is not included in the base installation of Git. With a Debian-based distro such as Ubuntu, you can get git2cl as follows:

sudo apt-get install git2cl

There typically are two ChangeLog files needed for releases; one in the main directory, and one in the po directory. You can generate these files with the following commands:

git log gramps-4.0.1.. --pretty --numstat --summary --no-merges | git2cl > ChangeLog
git log gramps-4.0.1.. --pretty --numstat --summary --no-merges -- po | git2cl > po/ChangeLog

External links