Note: You are currently viewing documentation for Moodle 1.9. Up-to-date documentation for the latest stable version is available here: Tracking Moodle CVS with git.

Obsolete:Tracking Moodle CVS with git: Difference between revisions

From MoodleDocs
m (typo error of moodle)
m (updated git for CVS users with updated url)
Line 122: Line 122:
* [http://wellington.pm.org/archive/200510/git/ cogito tutorial by martin langhoff]
* [http://wellington.pm.org/archive/200510/git/ cogito tutorial by martin langhoff]
* [http://www.kernel.org/pub/software/scm/git/docs/tutorial.html git tutorial]
* [http://www.kernel.org/pub/software/scm/git/docs/tutorial.html git tutorial]
* [http://www.kernel.org/pub/software/scm/git/docs/cvs-migration.html git for CVS users]
* [http://www.kernel.org/pub/software/scm/git/docs/gitcvs-migration.html git for CVS users]
* [http://www.kernel.org/pub/software/scm/git/docs/git-cvsimport.html git-cvsimport man page]
* [http://www.kernel.org/pub/software/scm/git/docs/git-cvsimport.html git-cvsimport man page]
* [http://www.kernel.org/pub/software/scm/cogito/docs/ cogito man pages]
* [http://www.kernel.org/pub/software/scm/cogito/docs/ cogito man pages]

Revision as of 07:05, 19 September 2008

Note: Work in progress. These are notes for users that are comfortable with CVS and other SCMs, doing branching, merging, etc.

Introduction

If you plan on doing complicated or sustained development on Moodle, you will benefit from a local revision control system. Centralized systems like CVS and SVN have limited capabilities for tracking vendor branches. For the ultimate experience you will want to use a system with distributed capabilities like git. Alternative tools for this include Mercurial, Darcs and SVK.

GIT was developed by Linus Torvalds specifically for the Linux Kernel team. It is fast, fast, fast. Its usage is slightly different from CVS/SVN, but, if kernel developers can handle it Moodle developers will find it easy  ;-)

Note: At the time of writing, GIT does not run natively on MSWindows platforms. Several projects are underway to port GIT to Windows but they are not complete yet. It is possible to use git on Win32 via Cygwin, but with slightly worse performance (note: v1.4.5 has several performance enhancements on Cygwin) though even on Cygwin GIT is much faster than CVS or SVN. If you are bound to the W32 platform and cygwin doesn't work for you, Mercurial may be an alternative. (--Martin Langhoff 14:04, 28 December 2006 (CST))

Obtaining git

You'll want:

  • Git (and its deps). It includes gitk, a very good UI for visualising project history.
  • cvsps (a dependency of git-cvsimport make sure you have the latest release)
  • an additional git porcelain (frontend)
    • qgit a nice GUI to view the project history, make commits, etc. Recommended! Note: qgit is tricky to compile by hand, get a .deb or an .rpm
    • stgit (StackedGIT is mainly for users doing heavy cherry picking. Only recommended for very advanced SCM users.)

Git is still developing quickly, but good mature versions are already available in packaged format. This guide is written with GIT v1.4 and Cogito v0.17 in mind. Ubuntu and Debian Backports have up-to-date packages for GIT, Cogito and related packages. RPMs are usually also available via YUM. If you want to be on the bleeding/leading edge you can follow the maint or master branches of the GIT development code.

Importing CVS

To begin we must import the CVS repository into a local git filesystem using git-cvsimport.

#!/bin/bash
CVSROOT=:pserver:anonymous@uk.cvs.moodle.org:/cvsroot/moodle
MODULE=moodle
INSTALLDIR=moodle
git-cvsimport -p x -v -k -o cvshead -d $CVSROOT -C $INSTALLDIR $MODULE &> cvsimport.log

(When might one want to use the -m -u and -s flags?)

-u purely cosmetic
-s slashes can cause problems but this doesn't seem to be the case with moodle
-m ?

This will run for a very long time as it checks out every revision of each file (including all branches). However, if you run the command after a successful initial run it will simply get the new revisions since it was last run. This creates a new git repository which can then be cloned and worked upon.

At the time of writing the size of a new Moodle git repository was approximately 866MB unpacked, and 75MB packed. Newer versions of git pack the project during import, so your resulting repository plus checkout should be a bit over 100MB. Still, it is a good idea to pack the repository to make it smaller and faster, running

git-repack -a -d 

With the -o cvshead flag, the "HEAD" of the CVS repo will appear as 'cvshead' in GIT, making things a lot clearer.

Importing CVS Faster

For initial imports, it is highly recommended that you fetch the CVS repository from one of Moodle cvs servers and run the initial cvsimport against your local copy of the repository.

For the more adventurous: Keith Packard wrote another importer that does a better job at the initial import, called parsecvs. I use parsecvs for the initial import and then git-cvsimport daily for the incremental imports. --Martin Langhoff 15:04, 19 July 2006 (WST)
It took me a few minutes to find the info in the Sourceforge docs on how to fetch the raw CVS repo via rsync. Just type 'rsync -av "rsync://moodle.cvs.sourceforge.net/cvsroot/moodle/moodle/*" .' (without the single quotes) and you'll be done --Iñaki Arenaza 17:54, 25 December 2006 (CST).
This rsync command line doesn't work as-is anymore, since the repository was moved from sourceforge. Some mirrors (at least es.cvs.moodle.org at this time) provide rsync, but some don't (like eu.cvs.moodle.org). Find the best mirror for you and update the rsync call accordingly.

After the initial import, you can run git-cvsimport against your favorite cvs.moodle.org mirror repository, or update your local copy via rsync as sas demonstrated in this script.

Creating a Working Copy

In order to use your repository you must clone yourself a working copy using git-clone.

(Let's assume your destination directory above was /pub/scm/moodle)

mkdir ~/git/moodle
cd ~/git/moodle
git clone /pub/scm/moodle.git

This will clone the git filesystem you created from the CVS import into a working copy that you may make changes to and commit to. You can then get updates from the main git repository that will be merged in amongst the changes to your local copy.

If you are using the Cogito tools, you can use cg-clone to do this instead:

cg-clone /pub/scm/moodle.git ~/git/moodle

Using git effectively with Moodle

Git can be used to intelligently track changes for creating client installs based off your own local, base, customisations which in turn tracks changes to the main Moodle CVS.

If you have a local git copy of the Moodle CVS repository you will have a number of heads such as: MOODLE_15_STABLE, MOODLE_16_STABLE, and so on. If you wish to create a new branch for your local customisations, you can base it off an existing HEAD (one of the CVS branches that exist in the main Moodle repository). If you wish to create a new local branch, mymoodle, based off the current stable 1.6 code you would:

cd /pub/scm/moodle.git
git branch mymoodle MOODLE_16_STABLE
git branch # lists all the current branches, should show mymoodle
git checkout mymoodle # you are now working on the mymoodle branch
# add some new files (i.e. themes, blocks, etc.)
cg-add -r .
cg-status # Will list your uncommited files
cg-commit -m "Added base customisations."

To return to the master HEAD, equivalent to the main Moodle CVS HEAD branch, you would have to use:

git branch master

If you were running a nightly script to pull new Moodle CVS updates into your main git repository via git-cvsimport, you should also merge any new changes into your local branch:

cd /pub/scm/moodle.git
git checkout mymoodle
cg-merge MOODLE_16_STABLE

If you wanted to use this custom local branch to create a new client install, you would use:

cg-clone /pub/scm/moodle.git#mymoodle /home/someclient/public_html/

This would create a new git repository from your branch that could be used to do a client install which can, in turn, have the client's custom files added to it. This entire process can be automated so that your mymoodle branch is tracking upstream changes from the Moodle CVS (MOODLE_16_STABLE in this example) and your client installs are tracking changes against your local branch.

Merging a patch from GIT into CVS

If you have cvs access, you can use the git-cvsexportcommit command to merge or cherry pick individual patches into upstream.

git-cvsexportcommit was initially written to do merges of NZOSVLE bugfixes into Moodle. Several tools and patches to GIT and Cogito come from the NZOSVLE team. Martin Langhoff 14:55, 19 July 2006 (WST)

If the patches merge cleanly, future updates will recognise the already-applied patch. In that sense the merger in git is smarter than the merger in Cogito, consider using git-pull rather than cg-update. Note that if you see conflicts using git-pull you will have to work a bit harder to resolve them. Make sure you are familiar with handling merge conflicts with pure git before trying this.

Preparing to merge large patch series or porting over to the next Moodle release

When you have a large set of patches to apply to CVS, or a large set of custom patches to apply on top of the next release of Moodle, you can use git-format-patch to see what are your unmerged patches. git-format-patch tries hard to spot already-merged patches and skip them.

If you are applying patches to CVS, you can then use git-cvsexportcommit or plain old patch -p1 filename. If you are applying them to a new git branch (as you would to merge them on top of a new Moodle release) then you want to be on that new branch, and use git-am -3 -k filename.

If you are using git-am, make sure you learn how to deal with merge conflicts, and the use of git-update-index.

Helpful Documentation

Moodle Forum Discussions