Brief introduction to Git
The development source code of Gramps is stored in the Git repository at GitHub.
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).
- 1 Install Git on your system
- 2 Obtaining a copy of the Gramps repository
- 3 Basic Work Flow
- 4 Types of branches
- 5 Stable version
- 6 Working with development branches
- 7 Useful Tips
- 8 Multiple Working Folders
- 9 Browse Git
- 10 Send your contribution without rights to push
- 11 git2cl
- 12 External links
Install Git on your system
sudo apt-get install git
yum install git-core
- Mac OS X (intel) Download git from here http://git-scm.com/download/mac.
- Mac OS X (PPC) Although the git download above is called 'git-18.104.22.168-intel-universal-snow-leopard.dmg', 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: http://jnorthr.wordpress.com/2013/03/29/building-a-git-client-1-8-2-on-apple-imac-ppc-osx-10-5-8/. 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 'org.eclipse.team.core 3.6.100' but it could not be found. Installing EGit version 2.0 from http://download.eclipse.org/egit/updates-2.0 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 user.name "John Smith" git config --global user.email firstname.lastname@example.org
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 GitHub account:
git clone https://github.com/gramps-project/gramps.git Gramps
You should see the downloading progress reported in your terminal.
If you have a GitHub account, use ssh instead:
git clone email@example.com:gramps-project/gramps.git Gramps
You can check your connection by:
ssh -T firstname.lastname@example.org
which should return:
Hi <name>! You've successfully authenticated, but GitHub does not provide shell access.
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:
To commit your changes locally, use the following command:
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.
- All developers should read Gramps Committing policies
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.
There are several versions of the Gramps source code in Git. The development branch for small changes and bug fixes is maintenance/gramps4.1
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 is known as a "tracking" branch.
To list the available branches, type:
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:
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
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
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
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
- Always do git pull --rebase before pushing changes to the server. If necessary get advice about handling conflicts.
- 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 setup.py 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 GitHub repository.
An alternative is to clone the GitHub 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.
Assuming that the directory structure would be:
~ +-Gramps +-repository +-.git +- etc +-gramps34 +-gramps40 +-gramps41 +-master
The approach would be:
- checkout from the GitHub 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 setup.py build
An alternative to the command line tools to view the Git repository is the online interface.
Send your contribution without rights to push
Since syncing a fork can create unwanted commits, you may need to rebase your pull request first. Remember to replace edx and master with the actual names of the remote repository (upstream) and the branch you're working on.
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