GitSuperRepoUsersGuide

Include here simple user-friendly instructions for using a Cactus super-repository

We provide a Git super-repo of the Einstein Toolkit. This page describes how to check it out and work with it. It is currently more of a tutorial than a User Guide.

Note that these instructions are a work in progress and will not currently work.

Much of this is too complicated to remember and understand. We need to make it much simpler, possibly by providing scripts.

Checking out

 git clone --recursive cactus@git.einsteintoolkit.org:einsteintoolkit Cactus

This takes about 10 minutes and will create a directory called Cactus containing the entire Einstein Toolkit and all its version history. When it is done, setup the git-module package which provides convenience functionality:

 cd Cactus
 ./bin/git-module setup
 . ~/.profile

Updating

To update the checkout, it is first a good idea to see what would be changed. First enter the top-level super-repo directory. You can get a list of the changes using

 git submodule foreach 'git --no-pager log --oneline ..remotes/origin/HEAD'

This assumes that the remote HEAD is the one that is checked out, which is not true for SimFactory, for example.

If this is OK, you can then update using:

 git pull
 git submodule update

Checking out a specific branch

If you want to use a particular Einstein Toolkit release, perhaps because the current development version is unstable, use

 git checkout ET_2011_06

The tree will be very quickly updated to match the release. All changed files will have updated datestamps, so you should be able to trust the Cactus make system to recompile only what is necessary. However, it might be safer to delete any configurations and build them again.

Committing

Git

For thorns whose source repositories are in Git already, you can commit and push as normal in the subrepositories. If they have been cloned from a public URL, as for the Einstein Toolkit URL above, you can use

 cd <submodule-path>
 git remote add upstream <new-url>
 git push upstream ...

SVN

For subrepositories which are SVN upstream (for example simfactory), you must first initialise the subrepository for committing:

 cd simfactory
 git checkout trunk
 git svn init -s --prefix=origin/ svn://...

You can now commit directly to the source SVN repository using

 git svn dcommit ...

assuming you have commit rights in the source SVN repository.

Mercurial

For Mercurial upstream repositories, it is more complicated, as there is no git-hg (equivalent to git-svn):

 hg clone <hg-url> <submodule-path>-upstream
 cd <submodule-path>-upstream
 vi .hg/hgrc # Add: 
             # [git]
             # intree = 1
             # [path]
             # git = ../<submodule-path>
 hg bookmark master -r default
 hg gexport # Can take quite a long time (~1 hour for carpet-hg)
 hg pull git # Pull from the git submodule
 hg push # Push to the upstream hg repo

This obviously has to be improved.

Viewing history

Each sub-repository is a separate fully-fledged Git repository, so you can go into each one and type "git status", "git log" etc. This works for repositories which are SVN upstream, because we use git-svn to convert the repositories to Git on the server. You can also use the usual graphical tools (we recommend GitX from [1] for Mac OS, and XXX for Linux) on each subrepository to visualise the log messages and patches, see which files have local changes, and interactively commit parts of files.

Viewing local modifications

You can see at a glance which of the submodules have local changes using

 git status

You can then go into each submodule and see those changes using git status or git diff.