Difference between revisions of "GENIE Quick SVN ref"

From SourceWiki
Jump to navigation Jump to search
 
(34 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
=What is Subversion?=
+
==What is Subversion?==
  
−
Subversion (abbreviated SVN) is the successor to CVS.  It is closely related to CVS and so many of the commands are the same.  For example, Subversion still has the commands '''checkout''', '''commit''' and '''update''', except that '''cvs update''' is replaced with '''svn update'''.  Happily this means that there is little re-learning required to use SVN instead of CVS.  If they were entirely alike, there would be no need for SVN, however.  Subversion addresses a number of the shortcomings of CVS.  For example, the command '''svn move''' now exists, wehereas files could not be renamed under CVS, without losing their revision history.
+
Subversion (abbreviated to SVN) is the successor to CVS.  It is closely related to CVS and so many of the commands are the same.  Subversion still has the commands '''checkout''', '''commit''' and '''update''', except that, for example, '''cvs update''' is replaced with '''svn update'''.  Happily this means that there is little re-learning required to use SVN instead of CVS.  If CVS and SVN were entirely alike, we would not get the advantages that Subversion brings.  Subversion addresses a number of the shortcomings of CVS.  For example, the command '''svn move''' now exists, which allows you to rename a file without losing it's history, something not possible under CVS.
  
−
=Using Subversion=
+
==Using Subversion on your local Machine==
  
−
First, just as it was with CVS, you will need a '''Subversion client''' installed on your machine.  If you are using linux, then you will most likely have the '''command line''' client already installed.  Try typing '''which svn''' to see if the clent is in your path.  SVN clients exists in both command line and nice GUI forms for just about any operating system. [http://tortoisesvn.tigris.org tortoisesvn] is popular for windows. [http://www.apple.com/downloads/macosx/development_tools/svnx.html SVNx] is popular for the Mac.  For more links see the [http://source/wiki/Subversion_links links page] on this wiki.
+
First, just as it was with CVS, you will need a '''Subversion client''' installed on your machine.  If you are using linux, then you will most likely have the '''command line''' client already installed.  Try typing "'''which svn'''" to see if the clent is in your path.  Command line and nice GUI clients for SVN are available for just about any operating system. [http://tortoisesvn.tigris.org tortoisesvn] is popular for windows. [http://www.apple.com/downloads/macosx/development_tools/svnx.html SVNx] is a good choice for the Mac.  For more links see the [http://source.ggy.bris.ac.uk/wiki/Subversion_links links page] on this wiki.
  
−
Once you have Subversion installed, you will need an username and password.  This will allow you to access the GENIE SVN repository.  Happily, this is considerably easier than for CVS.  You will be prompted for your password when required.  SVN caches your password, and so you often do not need to type it.
+
Once you have Subversion installed, you will need a username and password.  If you haven't already them, email Gethin.  You can get read-only access to the code by using the username "genie-user" and the password you would expect.  Happily, access is considerably easier than for CVS.  You will be prompted for your password when required.  SVN caches your password, and so you often do not need to type it.
  
−
Another big difference between CVS and SVN is that repositories are accessed through a URL.  For example, you might checkout GENIE from SVN by typing:
+
Another big difference between CVS and SVN is that repositories are accessed through a URL.  For example, you can get a copy of GENIE from SVN by typing:
−
<pre>svn checkout http://source.ggy.bris.ac.uk/subversion/genie/trunk --username <your_username> ~/genie</pre>
+
<pre>svn checkout https://svn.ggy.bris.ac.uk/subversion/genie/tags/rel-2-4-0 --username <your_username> ~/genie</pre>
  
−
=Quick Start=
+
==Quick Start==
  
−
See the above example, showing how to checkout the '''trunk''' of the GENIE repository.  (We will cover '''branches''' later.)  The examples below are for the command line client.
+
The above example showed how to obtain one of the stable releases of GENIE using the SVN command-line client.  See the [[GENIE:GENIE_Versions | GENIE versions page]] for more information about what stable releases are available and what they have been used for. We will continue with more command-line examples below:
 +
 
 +
If you are developing GENIE, you will want:
 +
* to get a '''working copy''' (using '''svn checkout''') of the code, rather than an '''exported copy'''.
 +
* to get hold of the HEAD version of the model:
  
−
To update an existing checkout, simple cd to the highest-level directory and type:
 
 
<pre>
 
<pre>
 +
svn checkout https://svn.ggy.bris.ac.uk/subversion/genie/trunk --username <your-username> ~/genie
 +
</pre>
 +
 +
(Note that '''svn co''' is synonimous with '''svn checkout''')
 +
 +
To update an existing checkout, simply cd to the highest-level directory (let's assume it's ~/genie) and issue the '''update''' command:
 +
<pre>
 +
cd ~/genie
 
svn update
 
svn update
 
</pre>
 
</pre>
 +
(You could update a sub-tree of your checkout by changing directory to, say, ~/genie/genie-embm and then calling "svn update", or you could just update a single file with svn update <filename>)
  
−
If you have created a new file, use:
+
Now cd to the directory you will be working in.
 +
 
 +
If you have created a new file, you must first add it to your local checkout.  (The action of adding it tells SVN that there is a new file which the repository must store, and schedules it for addition to the main repository when you next call "svn commit".  More of svn commit in a moment):
 
<pre>
 
<pre>
 
svn add <filename>
 
svn add <filename>
 
</pre>
 
</pre>
 +
or, for example:
 +
<pre>
 +
svn add *.f90
 +
</pre>
 +
To add a group of files en masse.
  
 
Similarly, to delete a file:
 
Similarly, to delete a file:
 
<pre>
 
<pre>
−
svn del <filename>
+
svn delete <filename>
 +
</pre>
 +
or:
 +
<pre>
 +
svn del *.f
 
</pre>
 
</pre>
  
−
Once you have made your local changes, use:
+
Once you have made your local changes, you should test them before committing any of them back to the repository.  Type:
 +
<pre>
 +
make test
 +
make testebgogs
 +
make testbiogem
 +
</pre>
 +
to run the IGCM- and EMBM-based short tests respectively (note that the BIOGEM test is based on an EBGOGS config').
 +
 
 +
You can check which files you have changed using:
 +
 
 +
<pre>
 +
svn status
 +
</pre>
 +
 
 +
Once your tests pass with an "**OK**", then you can go ahead and commit your changes.  To commit a single file, replace <my_modified_file> with the appropriate filename and provide a meaningful message log in the following command:
 +
<pre>
 +
svn commit -m "type your message here" <my_modified_file>
 +
</pre>
 +
 
 +
A successful commit will then advance the version number on the SVN repository by 1.  Thus we can see that '''SVN uses version numbers differently to CVS'''.  SVN gives the entire repository a version number and increments this whenever there has been a change.  This is unlike CVS, where individual files have their own individual version numbers.
 +
 
 +
We can commit ''all'' modified files in the current directory if we omit the filename:
 +
 
 
<pre>
 
<pre>
 
svn commit -m "type your message here"
 
svn commit -m "type your message here"
 
</pre>
 
</pre>
  
−
'''NB SVN uses version numbers differently to CVS'''.  SVN gives the entire repository a version number and increments this whenever there has been a change.  Thus--unlike CVS--individual files do have a version number.
+
A useful enhancement over CVS is the ability to move (or rename) a file without losing it's history:
 +
 
 +
<pre>
 +
svn move <before> <after>
 +
</pre>
  
 
To see the history of a given file, type
 
To see the history of a given file, type
Line 43: Line 92:
 
</pre>
 
</pre>
  
−
To check-out one of the stable releases of GENIE, you can use:
+
If things go a little pear-shaped with your checkout, you can go back to the last state obtained from the repository with:
 +
 
 
<pre>
 
<pre>
−
svn checkout https://source.ggy.bris.ac.uk/subversion/genie-test/tags/rel-2-1-0 --username <your_user_name> genie-2-1-0
+
svn revert --recursive <dir>
 
</pre>
 
</pre>
 +
where <dir> maybe your current dir, i.e "."<br>
 +
'''Note''' that --recursive will execute the command over a whole file-tree.
  
−
To find out more SVN options type:
+
To see the current status of your checkout, e.g. to check what files you have changed:
 +
<pre>
 +
svn status
 +
</pre>
 +
 
 +
To see the differences between your code and the 'head' code:
 +
<pre>
 +
svn diff <filename>
 +
</pre>
 +
 
 +
To find out more about the various SVN commands type:
 
<pre>
 
<pre>
 
svn --help
 
svn --help
 
</pre>
 
</pre>
 +
 +
or for the the usage of a particular command, e.g.:
 +
 +
<pre>
 +
svn copy --help
 +
</pre>
 +
 +
==More Advanced Functions==
 +
 +
Sometimes you would like to get a copy of the files in the repository as they were at a given date in the past.  You can  do this using options to either '''checkout''' or '''export'''.  For example, to obtain a working copy of the '''trunk''' of the repository as it stood on Christmas day 2006, you would type:
 +
 +
<pre>
 +
svn checkout -r {2006-12-25} http://source.ggy.bris.ac.uk/subversion/genie/trunk ./genie
 +
</pre>
 +
 +
You could be even more precise and also give a time of day--say 1pm.  This time we're getting a bare-bones export of just the files from a paricular '''branch''':
 +
 +
<pre>
 +
svn export -r {"2006-12-25 13:00"} http://source.ggy.bris.ac.uk/subversion/genie/my-branch ./genie
 +
</pre>
 +
 +
'''Note'''
 +
* that--of course--your branch must have existed at this point in time
 +
* also that since '''tags are snapshots''' this sort of retrospective does not apply to them
 +
* you may use '''-r <revision-number>''' if you know a particular revision number (perhaps from '''svn log''')
 +
 +
==Possible Pitfalls==
 +
 +
Watch out when copying directories that you delete the .svn information contained within. I (Greg Colbourn) copied the genie-atchem directory to make genie-rokgem not realising this and then had problems with "svn add" and "svn commit". After deleting the .svn directories from genie-rokgem and each of its subdirectories I was able to commit, but then I lost atchem!
 +
 +
==Further Documentation==
 +
 +
Rather than reinvent the wheel and try and document all aspects of Subversion here, it would be better if you looked at the [http://svnbook.red-bean.com | Subversion user manual].
 +
 +
==Appendices==
 +
 +
===Appendix A: Using svn:externals===
 +
 +
# cd to the directory to which you would like the external repository link.
 +
# make sure you have your EDITOR environment varaibale set to your preferred editor.
 +
# add the property by typing <pre>svn propedit svn:externls .</pre>
 +
# followed by creating an entry in your editor of the form <pre>/local/path http://blah/blah</pre> and save the file.
 +
# run <pre>svn up</pre>
 +
# and finally <pre>svn commit</pre>

Latest revision as of 10:36, 24 May 2010

What is Subversion?

Subversion (abbreviated to SVN) is the successor to CVS. It is closely related to CVS and so many of the commands are the same. Subversion still has the commands checkout, commit and update, except that, for example, cvs update is replaced with svn update. Happily this means that there is little re-learning required to use SVN instead of CVS. If CVS and SVN were entirely alike, we would not get the advantages that Subversion brings. Subversion addresses a number of the shortcomings of CVS. For example, the command svn move now exists, which allows you to rename a file without losing it's history, something not possible under CVS.

Using Subversion on your local Machine

First, just as it was with CVS, you will need a Subversion client installed on your machine. If you are using linux, then you will most likely have the command line client already installed. Try typing "which svn" to see if the clent is in your path. Command line and nice GUI clients for SVN are available for just about any operating system. tortoisesvn is popular for windows. SVNx is a good choice for the Mac. For more links see the links page on this wiki.

Once you have Subversion installed, you will need a username and password. If you haven't already them, email Gethin. You can get read-only access to the code by using the username "genie-user" and the password you would expect. Happily, access is considerably easier than for CVS. You will be prompted for your password when required. SVN caches your password, and so you often do not need to type it.

Another big difference between CVS and SVN is that repositories are accessed through a URL. For example, you can get a copy of GENIE from SVN by typing: 

svn checkout https://svn.ggy.bris.ac.uk/subversion/genie/tags/rel-2-4-0 --username <your_username> ~/genie

Quick Start

The above example showed how to obtain one of the stable releases of GENIE using the SVN command-line client. See the GENIE versions page for more information about what stable releases are available and what they have been used for. We will continue with more command-line examples below:

If you are developing GENIE, you will want:

  • to get a working copy (using svn checkout) of the code, rather than an exported copy.
  • to get hold of the HEAD version of the model:
svn checkout https://svn.ggy.bris.ac.uk/subversion/genie/trunk --username <your-username> ~/genie

(Note that svn co is synonimous with svn checkout)

To update an existing checkout, simply cd to the highest-level directory (let's assume it's ~/genie) and issue the update command: 

cd ~/genie
svn update

(You could update a sub-tree of your checkout by changing directory to, say, ~/genie/genie-embm and then calling "svn update", or you could just update a single file with svn update <filename>)

Now cd to the directory you will be working in.

If you have created a new file, you must first add it to your local checkout. (The action of adding it tells SVN that there is a new file which the repository must store, and schedules it for addition to the main repository when you next call "svn commit". More of svn commit in a moment): 

svn add <filename>

or, for example: 

svn add *.f90

To add a group of files en masse.

Similarly, to delete a file: 

svn delete <filename>

or: 

svn del *.f

Once you have made your local changes, you should test them before committing any of them back to the repository. Type: 

make test
make testebgogs
make testbiogem

to run the IGCM- and EMBM-based short tests respectively (note that the BIOGEM test is based on an EBGOGS config').

You can check which files you have changed using: 

svn status

Once your tests pass with an "**OK**", then you can go ahead and commit your changes. To commit a single file, replace <my_modified_file> with the appropriate filename and provide a meaningful message log in the following command: 

svn commit -m "type your message here" <my_modified_file>

A successful commit will then advance the version number on the SVN repository by 1. Thus we can see that SVN uses version numbers differently to CVS. SVN gives the entire repository a version number and increments this whenever there has been a change. This is unlike CVS, where individual files have their own individual version numbers.

We can commit all modified files in the current directory if we omit the filename: 

svn commit -m "type your message here"

A useful enhancement over CVS is the ability to move (or rename) a file without losing it's history: 

svn move <before> <after>

To see the history of a given file, type 

svn log <filename>

If things go a little pear-shaped with your checkout, you can go back to the last state obtained from the repository with: 

svn revert --recursive <dir>

where <dir> maybe your current dir, i.e "."
Note that --recursive will execute the command over a whole file-tree.

To see the current status of your checkout, e.g. to check what files you have changed: 

svn status

To see the differences between your code and the 'head' code: 

svn diff <filename>

To find out more about the various SVN commands type: 

svn --help

or for the the usage of a particular command, e.g.: 

svn copy --help

More Advanced Functions

Sometimes you would like to get a copy of the files in the repository as they were at a given date in the past. You can do this using options to either checkout or export. For example, to obtain a working copy of the trunk of the repository as it stood on Christmas day 2006, you would type: 

svn checkout -r {2006-12-25} http://source.ggy.bris.ac.uk/subversion/genie/trunk ./genie

You could be even more precise and also give a time of day--say 1pm. This time we're getting a bare-bones export of just the files from a paricular branch: 

svn export -r {"2006-12-25 13:00"} http://source.ggy.bris.ac.uk/subversion/genie/my-branch ./genie

Note

  • that--of course--your branch must have existed at this point in time
  • also that since tags are snapshots this sort of retrospective does not apply to them
  • you may use -r <revision-number> if you know a particular revision number (perhaps from svn log)

Possible Pitfalls

Watch out when copying directories that you delete the .svn information contained within. I (Greg Colbourn) copied the genie-atchem directory to make genie-rokgem not realising this and then had problems with "svn add" and "svn commit". After deleting the .svn directories from genie-rokgem and each of its subdirectories I was able to commit, but then I lost atchem!

Further Documentation

Rather than reinvent the wheel and try and document all aspects of Subversion here, it would be better if you looked at the | Subversion user manual.

Appendices

Appendix A: Using svn:externals

  1. cd to the directory to which you would like the external repository link.
  2. make sure you have your EDITOR environment varaibale set to your preferred editor.
  3. add the property by typing 
    svn propedit svn:externls .
  4. followed by creating an entry in your editor of the form 
    /local/path http://blah/blah
    and save the file.
  5. run 
    svn up
  6. and finally 
    svn commit
Retrieved from "https://source.geography.bristol.ac.uk/mediawiki/index.php?title=GENIE_Quick_SVN_ref&oldid=7350"