Personal tools
You are here: Home Documentation How-Tos Placing your Grok project under version control

Placing your Grok project under version control

This How-to applies to: Any version.
This How-to is intended for: Developer, Advanced Developer

Which files to keep and which to throw away when you save your Grok project.

Might be outdated! This document hasn't been reviewed for Grok 1.0 and may be outdated. If you would like to review the document, please read this post.

Very often, programmers find themselves wanting to save their projects to a version control system like Subversion, Bazaar, Git, or CVS. But it can be confusing to know what to save out of all the files that grokproject creates under your project directory! And, if you version-control the wrong ones, you could find that your project can be difficult to get working again when you check it back out.

The key is to recognize that much of your Grok project is created automatically from its buildout.cfg, and therefore should not be version-controlled. There are three reasons for not saving these files. First, they are each already defined or described by your buildout.cfg, and it is therefore redundant to place them in persistent storage. Second, they are often files which need to be different on every computer on which you place them because they have file names or paths to executables (like the Python interpreter) that are likely to be different on the various machines to which people check the project out. And, third, having the files in version control means that your version-control system and buildout will be constantly fighting as they overwrite the files' contents with new and old data, which can make deployment quite difficult.

Therefore, the files that you want to version-control are generally these:

# Save these files

src/yourproject/everything except *.pyc files
That is, you want to save the two files buildout.cfg and that define your project and describe how it should get built and run, and you want to save all of the source files and application content that you have generated under the src/ directory. But you should not save anything inside of the following directories, which are all auto-generated files that might have to look different on each system on which you check out and build your Grok project:
# Do NOT save these files

By omitting these directories, you leave buildout free to create these files afresh as they need to be on each system where you place your project.


Option #1: Rebuilding your project with the buildout command

Because you will need these files re-created when you check out your project, you will need to get a working copy of buildout available. Some people, I have heard, including people of quite high reputation in the Grok community, actually use easy_install to make the buildout program permanently available on their system:

# How to install the buildout command permanently
$ easy_install zc.buildout
Having this command available on your system means that you will typically find yourself doing something like this when you are ready to start work on a project that has been sitting in version control:
# Getting to work again

$ svn co http://.../myproject
$ cd myproject
$ buildout
$ bin/zopectl fg


Option #2: Using a bootstrap file to avoid installing buildout

Another method for checking your project back out, and that avoids having to install the buildout command on your system at all, is to place a copy of the file in your project:
# Grabbing for your project

$ cd my-project
$ wget*checkout*/zc.buildout/trunk/bootstrap/
You can then check this file in with the rest of your project, along with the other files you version-control, and it will be available whenever you check the project out. Then, re-activating your project just goes like this:
# Building out a freshly checked-out project

$ python ./
$ ./bin/buildout
$ ./bin/zopectl fg
Using means that anyone can work on your project without having to worry about installing Python commands on their system that they might never have heard of.

Backing up your live application data

Note that, as you run your project in production, you will want to be very careful to back up the following file:

# Back this file up, it contains your application data!

But as one does not typically use version control to back up raw application data, you should not actually place this file under version control! Instead you will copy it safely to another machine, or make sure it gets copied and placed on a back-up tape, to assure that you can restore your site with its content should the machine on which it is running ever be destroyed.


Version Control with Grok 1.0a2

Posted by Tim Cook at Feb 03, 2009 11:20 AM

This document at[…]/placing-your-grok-project-under-version-control

used to be correct and was very helpful.

Now with Grok 1.0a2 we have many issues with deploying an application via SVN. There seems to be hard coded paths in many places and I can't find a tool or switch on a tool that will fix them.

virtualenv myenv
cd myenv
source bin/activate
grokproject myproj

But .........
Everything in myproj/etc has hard coded paths. It isn't reproduced by anything other than grokproject.

So I have discovered that you should not put myproj/etc/ in version control along with myproj/parts/, myproj/bin/
myproj/develop-eggs/ and myproj/src/myproj.egg-info/

You must keep myproj/versions.cfg, myproj/buildout.cfg and myproj/

Create your project and commit it to version control.

Now your users/co-developers can do a checkout.
go to the myenv directory and activate their environment

execute: grokproject myproj

They will be prompted for an admin user and password. Then they will be prompted to see if they want to overwrite app.ppy The answer should be 'n' - for no.

Now cd myproj and execute buildout

I hope this works for you. It seems to be working ok for me.


Forgotten commands

Posted by Tim Cook at Feb 03, 2009 11:38 AM

source bin/activate

easy_install zc.buildout
easy_install grokproject

(assuming you have easy_install already installed as well).

Re: Forgotten commands

Posted by Roger Erens at Feb 05, 2009 02:35 AM
When creating a virtual environment, virtualenv also installs easy_install into it.