Some pointers about the subversion (svn) tool

The subversion (a.k.a. svn) tool

The subversion (svn) tool is what is used to keep track of the various versions of the PCM source codes. This is quite similar to the also well-known git tool. But we do not wish to have a religious debate.

Some useful svn commands

svn checkout

A checkout is simply downloading the (latest version of) reference code from the svn repository and saving a local copy. e.g. to download the entire PCM repository (i.e. "trunk" directory and sub-directories):

svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk

You can add an argument to rename the directory "trunk" to whatever you want, e.g. "PCM_sources"

svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk PCM_sources

Note that if you don't want to download the entire repository (likely the case if using only one of the PCMs) you can start by downloading an empty image of the "trunk":

svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk --depth empty

And later use "svn update" in "trunk" to only update desired sub-directories.

It is also possible to download a given revision of the trunk with "--revision ###" (where ### is the revision number), e.g. to download revision 1567:

svn --revision 1567 checkout https://svn.lmd.jussieu.fr/Planeto/trunk

svn update

To update your working copy to the latest revision, in your "trunk" directory issue command:

svn update

Note that you can "update" to any revision number (including past ones) by specifying revision number, e.g. to update (or revert) to revision 2567:

svn update --revision 2567

svn status

To know what files have been changes (with respect to your reference revision) or deleted or added in your distribution, use

svn status

which will return a list of files/directories changes. In practice each item of the list is prefixed by ? if the file is not versioned (i.e. not part of the svn repository), ! if it is missing (whereas it exists in the repository) or M if it is a modified version (i.e. you edited the file and made some changes to it, with respect to the reference)

svn diff

This command generates a "diff" between your local changes and local reference version, without extra arguments:

svn diff

The report will be for all files in current directory and sub-directories. One may add as a third argument the name of a given file to have only the diff concerning that file.

svn revert

If you have modified (or even deleted) a versioned file but want it back to its original pristine version, rather than undo the changes manually you can simply invoke:

svn revert thefileyouwantrestored

svn log

If you want to list all the revision messages (when one commits changes, one usually documents it with a short summary) use

svn log

Note that this will give you all the messages (logs) since the beginning of the repository...

If you know which revision number's log you want, you can specify it using --revision ###. e.g. to list the log for revision 666 only:

svn log --revision 666

And to list the latest log without specifying the revision number:

svn log --revision HEAD

For experts: how to commit your changes

IMPORTANT: This only concerns you if you are included in the core team of developers with commit privileges (this means that you have an svn account/password setup on the LMD server, contact the core team to set this up if needed).

1. You must be online (committing requires to connect and interact with the svn server)
2. You must have made you changes on (svn) versioned code, and that it is up-to-date with the repository ("svn update" is your friend).
3. It is recommended that you have set your SVN_EDITOR environment variable to point to your favorite text editor. For instance "vi":

declare -x SVN_EDITOR=vim

Now that things are ready for the commit (you might want to check one last time with "svn diff" that all your changes are in place and that you cleaned up any intermediate stuff), you can, in the directory where you made the changes, run the command:

svn commit

Note that if you want to only commit some files and not all those you modified in the current directory and subdirectories, you can can specify explicitely the paths&names of files to commit as extra arguments to "svn commit"

Once the "svn commit" command launched, your editor will open up, pre-filled with the differences in the code implied by your changes automatically inserted. All you need to do is fill in the first part of the message with comments about your changes (e.g. bug fix of ... , added feature as ..., code tidying, etc.). usually a few lines suffice. It is common practice to state in the first line of the commit which PCM is concerned ("Mars PCM", "Generic PCM", "Venus PCM", ...) and to sign the commit with your initials. Once you have entered your message, just save the file and this will automatically trigger the commit.

Once the commit triggered, you will need to specify you svn account login and password, at least the first time (svn can save and store these so that you don't need to enter them every time).

In case svn doesn't store your password, ensure you have store-passwords = yes in the following file:

~/.subversion/config

Some general guidelines about what to commit and when

In practice we work using a single-branch strategy. This means that any commit you make will affect everyone (who update their local copy following your commit). It is therefore important to keep in mind that:

• one should not commit any "work in progress" that breaks the code compilation or execution.
• before committing you should check that your code compiles and runs in "debug" mode.
• for traceability it make more sense to have individual commits concerning individual fixes or changes (i.e. avoid mixing some changes due to the implementation of a new parametrization with bug fixes concerning something else).
• other developers or users are not in your head, make your commit message as informative and useful as possible to them.

Some typical svn errors you may run into

If when trying t use an svn command you get a message of the likes of:

svn: E155036: The working copy at ....
is too old (format 29) to work with client version '1.10.2 (r1835932)' (expects format 31). You need to upgrade the working copy first.

This simply means that your svn tool has been upgraded to a more recent version and that you need to upgrade your current repository to follow up. In order to do that simply do

svn upgrade

And then you can keep using svn as before.

Some example commands of potential use in preparing a commit

Removing a file from the commit list using svn revert

In order to see only the files that are part of the versioned archive, it may be convenient to request only those (see svn status tutorial above). However, this may reveal files that you do not intend to commit. The example here is from the LMD.MARS/util directory where one had modified three (versioned) files

%svn status -q
M       aeroptical.F90
M       compile
M       simu_MCS.F90

The "compile" file was modified to find the NETCDF library on the local machine, but we do not want to add this to the archive (and annoy Ehouarn). So, we execute the command below which will replace the current version of compile with that of the current revision with which one is working. NOTE that if you need that version of the file, you should copy it to a different location or file name since it is replaced with a "fresh" copy.

% svn revert compile
Reverted 'compile'

% svn status -q
M       aeroptical.F90
M       simu_MCS.F90

And now one is ready to proceed to the next step of the commit.