CellML specification git tips

Writing down stuff as I work out how to use git in the development of the next version of the CellML specification.

The next version of the CellML specification is currently being written using DocBook and development is being managed with git. I am quite familiar with DocBook but have very little idea about git. Therefore, as I learn how to do various things with git I'll try to update this page so I don't have to keep working it out...

Useful information?

I'm currently doing all this on a Fedora Core 6 (x86_64) linux machine running git version 1.5.2.2.

Andrew's draft

Andrew Miller has what is currently the primary draft of the specification in his git repository at http://repo.or.cz/w/cellml-draft-miller.git. You can grab a local instance of this repository with the command:

git clone http://repo.or.cz/r/cellml-draft-miller.git cellml-draft-miller

where cellml-draft-miller is the directory that will be created to hold the local clone of the repository. You can then go into that directory and see that there is only one file: ALL-WORK-ON-BRANCHES; which simply indicates that you need to switch to a branch in order to see the useful stuff. You can list out all the branches like this:

~/cellml-draft-miller> git branch
* master
~/cellml-draft-miller> git branch -r
  origin/HEAD
  origin/master
  origin/normative
  origin/normative-andre

which shows that there is just the one local branch (master) and a bunch of remote branches (I think). While I read that I could swap to a different branch with the command git checkout <branch>, trying to do that with the remote branches results in a helpful error message which leads to the command:

~/cellml-draft-miller> git checkout -b origin/normative
~/cellml-draft-miller> git branch
  master
* origin/normative

showing that you have now switched to the normative branch from Andrew's remote repository. Now I think git pull should keep that up-to-date with any changes made in the normative branch of Andrew's repository.

Andre's fork

In order to get somewhere public to push any changes I might come up with, and following Andrew's suggestion I have forked the cellml-draft-miller project at repo.or.cz to create the cellml-draft-miller/andre project. It seems that this can't be used immediately as it has no content and git doesn't let you clone empty repositories. So I edited my checked out copy of cellml-draft-miller (normative branch), and then did:

~/cellml-draft-miller> git commit -a -s -m "...."
~/cellml-draft-miller> git push --all git+ssh://repo.or.cz/srv/git/cellml-draft-miller/andre.git

where the first command commits the changes I had made to my local git repository and then the second one pushes the local repository to the remote one. Seems I still have a bit to learn though as my repository now has the branches master (identical to Andrew's) and origin/normative (contains the equivalent of Andrew's normative branch). However, I can now clone the repository and work on it using:

~/> git clone --reference cellml-draft-miller http://repo.or.cz/r/cellml-draft-miller/andre.git
~/andre> git checkout -b origin/origin/normative

where the clone references my existing local cellml-draft-miller repository in order to save bandwidth in grabbing the new andre repository. I really have no idea what I'm doing. Each time I do a push I end up making a new branch (origin/origin/normative and origin/origin/origin/normative). Not really sure whats going on, but I just did a git checkout -b normative and my local repository happily changed to the normative branch?!? It looks like I can now push without the --all and have the remote normative branch updated.

I also found a note saying this was a good thing to do:

~/andre> git config --global user.name "Your Name Goes Here"
~/andre> git config --global user.email email@example.com

and as I have a separate user at home and at work for repo.or.cz (can't add to the ssh keys after creating the user), having done this at home I hopefully will show up in the logs as the same person?

So, just to summarise, here is a typical extended session...

~/> git clone http://repo.or.cz/r/cellml-draft-miller/andre.git
~/andre> git checkout origin/normative
~/andre> git checkout -b normative
~/andre> <edit/view/validate/etc.>
~/andre> git commit -a -m "Log message that is nice and meaningful"
~/andre> <edit/view/validate/etc.>
~/andre> git commit -a -m "Log message that is nice and meaningful"
.
.
.
~/andre> git push git+ssh://USER@repo.or.cz/srv/git/cellml-draft-miller/andre.git

Well, still not right as I can't seem to push changes from one local archive to the remote one and then pull them back into another one. I'm guessing I have missed something obvious somewhere...ah ha! can update with something like:

~/andre> git pull http://repo.or.cz/r/cellml-draft-miller/andre.git normative

which will pull the changes from the normative branch in my remote repository onto the current branch in the local repository. Furthermore, you can pull changes from other repositories and commit them and push them out with:

~/andre> git pull http://repo.or.cz/r/cellml-draft-miller.git normative
~/andre> git commit -a -m "merging Andrew's latest changes"
~/andre> git push git+ssh://USER@repo.or.cz/srv/git/cellml-draft-miller/andre.git

not sure if maybe git merge should be used in there somewhere?

Useful links

These have helped me in one way or another: