Brief introduction to Git

From Gramps
Revision as of 22:00, 7 November 2013 by Jralls (talk | contribs) (Types of branches: Move the statement about the master branch from Basic Work Flow.)
Jump to: navigation, search

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

http://git.code.sf.net/p/gramps/source/.

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).

Obtaining a copy of the Gramps repository

Install Git on your system.

  • Debian/Ubuntu: apt-get install git
  • Fedora: yum install git-core

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

git config --global user.name "John Smith"
git config --global user.email [email protected] 

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 http://git.code.sf.net/p/gramps/source Gramps

You should see the downloading progress reported in your terminal.

If you have a SourceForge account, use ssh instead:

git clone ssh://<username>@git.code.sf.net/p/gramps/source Gramps

You will need a SSH Key in order to authenticate using this method.

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.

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 development happens in the master branch. New releases never come from the master branch.
  • maintenance - There are many maintenance branches. 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 maintenance branches. The purpose of maintenance branches is to allow the line of code to stabilize while new features are added in the master branch.
  • 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.
  • sandbox - These are meant for experimentation purposes. If you want to explore some ideas or try out some changes that would break the master branch or prototype something that has not made it to a GEP you can create a sandbox branch. These should be short lived. As soon as you have finished please remove the branch. We reserve the right to remove any sandbox branch that has not been touched for 12 months. sandbox branches should use the following naming convention <username>-<descriptive text> e.g. hippy-prototype-rss-idea. 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/gramps52.

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 show remote origin

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

git checkout -b gramps40 origin/maintenance/gramps40

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>

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

Workflow

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

Some procedural recommendations

  1. Always do 'git pull' 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.
  • logs are important -- please give some thought to the log message. All developers should read the Committing policies.

Browse Git

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

git2cl

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