What is Git?

Git is a distributed version control system (VCS) originally developed by Linus Torvalds for managing Linux source code without requiring a central server. It is also the primary VCS used by the Gnome and Free Desktop projects. You can get the latest version for your system and read a rich variety of online documentation at Git's Home. In particular, Pro Git by Scott Chacon is available in several languages for free online reading at Git Book, where you can also download the English version as a PDF, ebook, or mobi.

What has that to do with Gnucash?

We have converted from Subversion to Git in order to take advantage of its branching and merging facilities, which are much richer than those provided by Subversion. Our public repositories are mirrored on Github: for code, documentation, and for the website. These are updated from the primary repository by commit hooks, so barring technical problems changes appear in these repositories within a few seconds of being committed to the primary.

Using the Github Repository

Non-Committers

Set-Up

Just clone the repository as usual:

 git clone https://github.com/Gnucash/gnucash.git

Note that the default branch in git is master. In the old svn days this was trunk. For convenience for users migrating from svn a trunk branch has been set up as an alias for the master branch but you are encouraged to switch to master as your main branch.

When you have patches, use

 git format-patch origin/master..master

(or git diff) in the root directory of your local repository to prepare them; then add the patchfile as an attachment to the appropriate bug report.

If you have a Github account, you could as well use Github's "fork" feature to set up a clone on GitHub. And then clone from that repository instead (note that this is a read-write enabled clone):

 git clone git@github.com:<YOUR-GITHUB-USERNAME>/gnucash.git

Note that this clone command takes a url in a different format. With this form you will be able to push your local changes to your GitHub account as usual:

 git push origin master

Continue with ...

#Committers

Patches

If you're going to be submitting patches:

Create a branch to work in. We prefer that patches are to the master branch. If the patch needs to be backported, the developer who pushes it can modify the commit message, but if the code in the area you're working on has diverged significantly you can help out by providing separate patches (you'll need two working branches in that case).

 git checkout master
 git branch working-master

Rebase your working branch onto the target branch often so that you stay in sync:

 git rebase master working-master

Open a bug in Bugzilla to attach your patch to if one doesn't already exist.
Write good commit messages in which the bug number and summary are the first line. Skip one line, then describe the patch. For example:

 [Bug 673193] - Possible Register migration to TreeView
 
 Update the old register rewrite branch to work with the currently-released Gtk2.

Use git rebase -i as necessary to make a clean series of patches for complex changes.
Be sure to do a fresh rebase from the target branch and a make check to ensure that everything works
Use git format-patch to create the actual patches from your commits:

 git rebase master working-master
 git format-patch master

Attach the resulting patch(es) to the bug report.

Committers

Since 2014-02 all GnuCash repositories are pure git repositories:

gnucash
gnucash-docs
gnucash-htdocs (see #Conversion Notice)

Set up

Note: this set up presumes you already have commit access to the GnuCash repositories on code.gnucash.org. If you don't but believe you should, ask for this on the gnucash-devel mailing list. You'll need to generate a key-pair and provide the public half to the GnuCash repository administrator. To generate a key pair use

 ssh-keygen -t rsa -b 1024 -f gnucash-key

You can use any name you like instead of "gnucash-key".

You will also be prompted for a passphrase, with the option to leave it blank. If you provide a passphrase, you will be prompted to provide it every time you use your key. If you don't, anyone who gains access to your key can connect to whatever servers you protect with it.

Once you have the key configured correctly and have provided it to the GnuCash repository administrator, try

 ssh -i gnucash-key git@code.gnucash.org

You'll get the usual ssh question about the fingerprint for a new host. It should be 20:23:3d:df:f3:13:34:c1:32:ca:11:77:24:21:98:01. If it is, answer "yes" to add it to your known hosts file. If you get a message followed by a list of repositories, your setup is correct and you can proceed.

Next, you'll want to to configure your local ssh client to always provide this key when connecting to code.gnucash.org. In addition, ssh should always connect as user 'git'.

On linux, you can set this up by adding the following lines in your ssh config file (~/.ssh/config):

Host code.gnucash.org
IdentityFile ~/.ssh/gnucash-key
User git

Now clone the Github repository the same way as #Non-Committers. Since changes should not be pushed to the github repository, a good way to make sure that this doesn't happen by mistake is to use the same read-only URI given above for non-committers. Alternatively, fork the Gnucash repository to your Github account and clone that (use the read-write URI in that case).

Next add the repository on code.gnucash.org as a second remote, for example as 'upstream'.

 git remote add upstream git@code.gnucash.org:gnucash

That's it.

Git and Microsoft Windows

To set up ssh with the MSYS client, proceed exactly as above.

For [TortoiseGit], you'll also need PuttyGen and Putty from [PuTTY]. Setting up Pageant to work with TortoiseGit is a bit involved, so we'll go through it step-by-step:

1. Use PuttyGen to convert your private key into Putty format. Launch puttygen, click the "load" button and select your private key file, then click the "save private key" button to save it in putty format.

2. Set up a Putty profile: Start Putty.

Set the Host URL to code.gnucash.org, port 22 on the Session page
Open Connection:SSH:Auth and at the bottom of the panel, for "Private key file for authentication" browse for the converted keyfile you made in the previous step.
Open Connection:Data and enter 'git' in the "Autologin username" text entry.
Return to the Session panel, enter a name (if you use code.gnucash.org configuring TortoiseGit will be less confusing) in the text entry named "Saved Sessions" and click the "save" button.
Click "open". If everything is done correctly, a command window will open and you'll see that message about terminal sessions not being allowed. If you are instead prompted for a password, you have messed up the username or key somehow and will need to contact the server admin to get your IP address unblocked.

3. Set up TortoiseGit:

Right-click a folder in Windows™ Explorer and select TortoiseGit:Settings. At the bottom of the Network panel of the resulting dialog box, click the "Browse" button for SSH Client and navigate to C:\Program Files\TortoiseGit\bin\TortoisePlink.exe, click "open" in the file chooser, the "OK" to dismiss the Settings box.
Right-click on a folder into which you want to check out (or already have checked out) Gnucash. If it's a fresh checkout, select TortoiseGit Checkout; otherwise select TortoiseGit:Relocate. Enter the URL as ssh://the-putty-session-name/gnucash. (Remember earlier where we said it would be less confusing if you use code.gnucash.org for the session name? That's because if you did the URL will be ssh://code.gnucash.org/repo/gnucash.)

You should now be able to commit changes via TortoiseGit.

Committing

Committing is simple:

 git add
 git commit

These two commands are used to record your changes locally.

 git push upstream local-branch:remote-branch

Will push your changes back to the master repository.

Branching and Merging

The "canonical" repositories at code.gnucash.org and their mirror at github.com/Gnucash have 2 active branches:

master is the development branch. All new features should be committed to this branch and this branch only. Unstable releases during the beta period leading up to a new stable release series will be tagged on this branch and the tarballs generated from the tag commits. Bugs reported against an unstable release should be checked to see if they exist on the stable release; if they do they should be reassigned to the stable release and fixed on maint, then merged.

maint is the current stable release branch. All bugs reported on the released version should have the fixes committed to this branch and then merged to master. Stable releases will be tagged on this branch and the tarballs generated from the tag commits.

There are also archival branches, one for each stable release series no longer under development. Note that before 2.6 we used Subversion or CVS for version control and the practices were different, so you'll see different commit patterns when looking at historical branches.

The gnucash repository contains an archive branch which tracks master up to the point that the last subversion feature branch (webkit, if you're curious) was merged, except that new merge commits have been added to link the feature branch merges. It shows the merge points in the right order, but the merge commit dates are all from early 2014. It is of historical interest only.

There are several abandoned feature branches which were never integrated into GnuCash. They are also present for historical interest only.

Bugs and New Features

To repeat the policy in the description of the active branches:

Bug fixes should always be rebased onto the maint branch then merged to master unless either they don't affect maint or they are not going to be fixed on maint because the required changes are complex enough that it would risk making maint unstable.
New Features are always rebased or merged onto master. New features are not allowed on maint.

Small changes, which can be completed quickly and in a single commit, do not require a feature branch. Larger changes which might require more than one commit or take more than a few hours to write and test should be done on a private branch which is rebased onto the appropriate main branch. This helps keep the main branch's history linear, which in turn makes it easier to read and displays better in a graphical tool. Major changes, which are completed in stages which are made public in parts or which for any reason are best visualized as standing apart from the main branch, should be merged with --no-ff to prevent them from fast-forwarding the main branch.

Bug Fix Feature Branch Example

 git checkout -b my-bug-fix maint
 # make changes, commit, test, fix, etc.
 git checkout maint
 git pull --rebase
 git rebase maint my-bug-fix
 # make && make check to ensure that you're not pushing a broken build!
 git push upstream maint
 git checkout master
 git pull --rebase
 git merge maint
 # rebuild and make check again
 git push upstream master

Major Feature Branch Example

 git checkout -b my-new-feature master
 # write and test the first phase of your feature, committing often.
 git checkout master
 git pull --rebase
 git merge --no-ff my-new-feature
 # rebuild and make check for safety
 git push upstream master
 git checkout my-new-feature
 # write the next phase and repeat until done.

Link Bugzilla Entries

Often commits are related to Bugzilla entries. In this case the first line should contain

Bug #<bug number>:<bug title> or
Bug #<bug number> - <bug title>.

If trac sees the hash sign (#), it should create a link to that bugzilla entry.

Other options exists as well; feel free to edit this wiki page.

Back to Development Process

Collaboration

With rare exceptions we don't want to clutter the master repository with feature branches, so how can two developers collaborate on one? There are several ways to go about it: You can pass patches between you over email, chat, or carrier pigeon; Git is designed to handle that easily (except for carrier pigeon transport, as that requires retyping the patch, which is a pain). You can arrange for all of your repositories to be available on the net, and git pull amongst yourselves. Or you can use one of the public repositories like Github or Gitorious to manage your changes.

Accessing GnuCash BugZilla from Git

There is a plugin, called git-bz, written for Git that allows it to talk to BugZilla and do things with bugs like attach patches, add comments, mark as fixed, etc.–all from the command line. See the git-bz page for details.

Conversion Notice

For some time now the gnucash-htdocs repository has been used to store both the website and a compiled version of our documentation in html, pdf, ebup and mobi formats. The problem with this is that the compiled documentation is pretty large. The repository is currently over 800Mb in size and increasing with each release. That means that over time a simple clone of the repository will cost increasingly more bandwidth and diskspace.

People that wish to work on the website don't need this compiled documentation so the large download is an unnecessary burden. We have decided to fix this by splitting off the compiled documentation into a separate repository. It's only relevant for a release manager. After the split, the gnucash-htdocs repository will be regenerated without the docs history.

As we are doing maintenance on this repository we will remove the "trunk" branch as well in favour of the more git-typical "master" branch.

If you have your own clone of the gnucash-htdocs git repository you will have to reclone the new repository if you want to enjoy the smaller footprint. If you have local changes you'll want to preserve them. So instead of deleting the directory rename it. For the examples we'll call it gnucash-htdocs-old, and we'll clone into gnucash-htdocs-new. That's just to make sure we don't forget which is which. After the import process is complete, you can remove gnucash-htdocs-old and rename gnucash-htdocs-new.

You've been assiduous about always using git pull --rebase, right? No? You've got changes mixed into master? No matter. rebase to the rescue: (I'm using master as an example here, but it could be any tracking branch.)

 cd gnucash-htdocs-old
 git pull --rebase
 git branch -m master foo #This is your new feature branch. You can call it anything you like
 git branch -t master origin/master
 git rebase master foo

There. Now all of your changes are in a nice feature branch. You might have to reconcile some conflicts, but better sooner than later, eh? If you already have feature branches -- we'll use foo for our example -- just make sure that it's up to date with its tracking branch:

 git checkout master
 git pull --rebase
 git rebase master foo

Now you're ready to export your changes. Do this one feature branch at the time. Create a set of patches for your feature branch:

 cd ../gnucash-htdocs-old
 git checkout foo
 git format-patch --stdout master > ../foo.mbox

And import your branch foo into the new repo:

 cd ../gnucash-htdocs-new
 git checkout master
 git checkout -b foo
 git am ../foo.mbox

That's it. Repeat for each feature branch and tracking branch. When you're done and really, really sure that everything is properly set up, you can delete gnucash-htdocs-old and any foo.mbox you created.

Note: When you run git checkout master in gnucash-htdocs-new, git should respond with

 Checking out files: 100% (1247/1247), done.
 Branch master set up to track remote branch master from origin.
 Switched to a new branch 'master'

If it doesn't, then it may have gotten confused. If

 git log --oneline -n 10

doesn't produce the expected results,

 git branch -D master
 git branch -t master origin/master

To get the proper master branch.

Github Forks: If you have made a Github fork you will need to make sure that your local repo is current and then delete the fork and re-fork the regenerated repository, then proceed according to the instructions above, finally pushing any new branches back to your Github fork.

Git

Contents

What is Git?

What has that to do with Gnucash?

Using the Github Repository

Non-Committers

Set-Up

Patches

Committers

Set up

Git and Microsoft Windows

Committing

Branching and Merging

Bugs and New Features

Link Bugzilla Entries

Collaboration

Accessing GnuCash BugZilla from Git

Conversion Notice

Related Topics

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Related Sites

Contributing

Tools