https://source.geography.bristol.ac.uk/mediawiki/api.php?action=feedcontributions&feedformat=atom&user=JprenaudSourceWiki - User contributions [en]2026-04-07T00:25:00ZUser contributionsMediaWiki 1.35.8https://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5655General use of the TELEMAC system2008-09-19T09:57:01Z<p>Jprenaud: /* Environment set-up */</p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
The current modules are:<br />
* TELEMAC-2D, 2D flood inundation<br />
* SISYPHE, 2D river bed evolution<br />
* ESTEL-2D, 2D groundwater flow and contaminant transport<br />
* ESTEL-3D. 3D groundwater flow and contaminant transport<br />
More modules (3D hydrodynamics, waves ...) could be added if necessary. Just ask.<br />
<br />
= Linux =<br />
The TELEMAC system is installed centrally on "dylan" which the Linux operating system (CentOS).<br />
'''You will need to log into dylan and use linux commands to run TELEMAC jobs'''. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this. Ask the scientific computer officer for pointers if you need some and get some training if required.<br />
<br />
"Note that because the pre- and post-prtocessors run on MS Windows, I personally encourage people to use the Linux shell only to start the TELEMAC jobs and use the MS Windows environment for editing files etc... See [[General_use_of_the_TELEMAC_system#A_note_about_ASCII_files | note below]] for a word of warning about MS Windows text editors." [[User:Jprenaud|JP Renaud]] 18:25, 18 September 2008 (BST)<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system, for instance:<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
Note that if you log in another machine (i.e. not dylan) you might get an error message about "/home/telemac" not existing or file not found. This is normal, the location probably does not exist of the other machine... Live with it or adapt the .bashrc so that the files are sourced only on dylan. For instance, you could use:<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
# Only done on dylan<br />
if [ `hostname | grep dylan` ]; then<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
fi<br />
</pre><br />
<br />
= Test = <br />
<br />
Telemac-2d includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured environment. Now go and do some real work with your own files<br />
<br />
= A note about ASCII files =<br />
<br />
Windows and Linux treat end of line in ASCII files differently. This means that if you edit a steering file on Windows using MS Notepad, you might have problems running the simulation on Linux. However, it is sometimes cumbersome to use text editors on Linux via an ssh session. The solution is too use a good text editor and configure it to use Unix type end of line characters. [http://www.scintilla.org/SciTE.html Scite] is a very good text editor for the MS Windows environment.<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. However, a few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number of processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Note that dylan has 8 cores so the system is configured to run with '''8 processors as a maximum'''.<br />
<br />
Put "0" to run in scalar mode. "1" runs in parallel mode but with one processor only, so "0" and "1" should give the same results despite using different libraries.<br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. Note that this needs to be done once per login, not for each job.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster this time, maybe 30 seconds or so instead of 55 seconds. It is not a lot faster (certainly not 8 times faster!) but this is because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time. With biggers meshes and longer sinmulations, you should get a better acceleration.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre><br />
<br />
It is also possible to run TELEMAC on the University cluster, bluecrystal. This is described on another page (not finished yet but will be done soon).<br />
<br />
=Changing between versions of the TELEMAC system=<br />
The basic configuration allows the user to switch transparently between versions of the TELEMAC system via the commands v5p8 and v5p9:<br />
<pre><br />
$ v5p9<br />
Switched to TELEMAC version: v5p9<br />
</pre><br />
<br />
Version v5p9 is under development and you are encouraged not to use it though! It might be that a developer asks you to test something under version v5p9 so this is merely to make this easier.<br />
<br />
=A note about binary files=<br />
TELEMAC was traditionally run on large Unix machines which have a different way of storing binary data than the PCs used today. They are called "big endian" systems and most PCs are "little endian" machines. By convention, TELEMAC uses files in the big endian format. Luckily, the pre- and post-processors running on the PCs can output or read big endian.<br />
<br />
In terms of the TELEMAC code itself, the Intel compiler is very handy as the big or little endian type can be changed without having to recompile the whole code. This is done with the environmental variable F_UFMTENDIAN. It defaults at "big" (see /home/telemac/intel_env). This can be changed for particular applications but really you should not have to do anything.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5654General use of the TELEMAC system2008-09-19T09:55:57Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
The current modules are:<br />
* TELEMAC-2D, 2D flood inundation<br />
* SISYPHE, 2D river bed evolution<br />
* ESTEL-2D, 2D groundwater flow and contaminant transport<br />
* ESTEL-3D. 3D groundwater flow and contaminant transport<br />
More modules (3D hydrodynamics, waves ...) could be added if necessary. Just ask.<br />
<br />
= Linux =<br />
The TELEMAC system is installed centrally on "dylan" which the Linux operating system (CentOS).<br />
'''You will need to log into dylan and use linux commands to run TELEMAC jobs'''. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this. Ask the scientific computer officer for pointers if you need some and get some training if required.<br />
<br />
"Note that because the pre- and post-prtocessors run on MS Windows, I personally encourage people to use the Linux shell only to start the TELEMAC jobs and use the MS Windows environment for editing files etc... See [[General_use_of_the_TELEMAC_system#A_note_about_ASCII_files | note below]] for a word of warning about MS Windows text editors." [[User:Jprenaud|JP Renaud]] 18:25, 18 September 2008 (BST)<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system, for instance:<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
Note that if you log in another machine (i.e. not dylan) you might get an error message about "/home/telemac" not existing or file not found. This is normal, the location probably does not exist of the other machine... Live with it or adapt the .bashrc so that the files are sourced only on dylan. For instance, you could use:<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
# Only done on dylan<br />
if [ `hostname` | grep dylan ]; then<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
fi<br />
</pre><br />
<br />
= Test = <br />
<br />
Telemac-2d includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured environment. Now go and do some real work with your own files<br />
<br />
= A note about ASCII files =<br />
<br />
Windows and Linux treat end of line in ASCII files differently. This means that if you edit a steering file on Windows using MS Notepad, you might have problems running the simulation on Linux. However, it is sometimes cumbersome to use text editors on Linux via an ssh session. The solution is too use a good text editor and configure it to use Unix type end of line characters. [http://www.scintilla.org/SciTE.html Scite] is a very good text editor for the MS Windows environment.<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. However, a few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number of processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Note that dylan has 8 cores so the system is configured to run with '''8 processors as a maximum'''.<br />
<br />
Put "0" to run in scalar mode. "1" runs in parallel mode but with one processor only, so "0" and "1" should give the same results despite using different libraries.<br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. Note that this needs to be done once per login, not for each job.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster this time, maybe 30 seconds or so instead of 55 seconds. It is not a lot faster (certainly not 8 times faster!) but this is because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time. With biggers meshes and longer sinmulations, you should get a better acceleration.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre><br />
<br />
It is also possible to run TELEMAC on the University cluster, bluecrystal. This is described on another page (not finished yet but will be done soon).<br />
<br />
=Changing between versions of the TELEMAC system=<br />
The basic configuration allows the user to switch transparently between versions of the TELEMAC system via the commands v5p8 and v5p9:<br />
<pre><br />
$ v5p9<br />
Switched to TELEMAC version: v5p9<br />
</pre><br />
<br />
Version v5p9 is under development and you are encouraged not to use it though! It might be that a developer asks you to test something under version v5p9 so this is merely to make this easier.<br />
<br />
=A note about binary files=<br />
TELEMAC was traditionally run on large Unix machines which have a different way of storing binary data than the PCs used today. They are called "big endian" systems and most PCs are "little endian" machines. By convention, TELEMAC uses files in the big endian format. Luckily, the pre- and post-processors running on the PCs can output or read big endian.<br />
<br />
In terms of the TELEMAC code itself, the Intel compiler is very handy as the big or little endian type can be changed without having to recompile the whole code. This is done with the environmental variable F_UFMTENDIAN. It defaults at "big" (see /home/telemac/intel_env). This can be changed for particular applications but really you should not have to do anything.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5653General use of the TELEMAC system2008-09-18T17:37:16Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
The current modules are:<br />
- TELEMAC-2D, 2D flood inundation<br />
- SISYPHE, 2D river bed evolution<br />
- ESTEL-2D, 2D groundwater flow and contaminant transport<br />
- ESTEL-3D. 3D groundwater flow and contaminant transport<br />
More modules (3D hydrodynamics, waves ...) could be added if necessary. Just ask.<br />
<br />
= Linux =<br />
The TELEMAC system is installed centrally on "dylan" which the Linux operating system (CentOS).<br />
'''You will need to log into dylan and use linux commands to run TELEMAC jobs'''. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this. Ask the scientific computer officer for pointers if you need some and get some training if required.<br />
<br />
"Note that because the pre- and post-prtocessors run on MS Windows, I personally encourage people to use the Linux shell only to start the TELEMAC jobs and use the MS Windows environment for editing files etc... See [[General_use_of_the_TELEMAC_system#A_note_about_ASCII_files | note below]] for a word of warning about MS Windows text editors." [[User:Jprenaud|JP Renaud]] 18:25, 18 September 2008 (BST)<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system, for instance:<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
Note that if you log in another machine (i.e. not dylan) you might get an error message about "/home/telemac" not existing or file not found. This is normal, the location probably does not exist of the other machine... Live with it or adapt the .bashrc so that the files are sourced only on dylan.<br />
<br />
= Test = <br />
<br />
Telemac-2d includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured environment. Now go and do some real work with your own files<br />
<br />
= A note about ASCII files =<br />
<br />
Windows and Linux treat end of line in ASCII files differently. This means that if you edit a steering file on Windows using MS Notepad, you might have problems running the simulation on Linux. However, it is sometimes cumbersome to use text editors on Linux via an ssh session. The solution is too use a good text editor and configure it to use Unix type end of line characters. [http://www.scintilla.org/SciTE.html Scite] is a very good text editor for the MS Windows environment.<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. However, a few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number of processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Note that dylan has 8 cores so the system is configured to run with '''8 processors as a maximum'''.<br />
<br />
Put "0" to run in scalar mode. "1" runs in parallel mode but with one processor only, so "0" and "1" should give the same results despite using different libraries.<br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. Note that this needs to be done once per login, not for each job.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster this time, maybe 30 seconds or so instead of 55 seconds. It is not a lot faster (certainly not 8 times faster!) but this is because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time. With biggers meshes and longer sinmulations, you should get a better acceleration.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre><br />
<br />
It is also possible to run TELEMAC on the University cluster, bluecrystal. This is described on another page (not finished yet but will be done soon).<br />
<br />
=Changing between versions of the TELEMAC system=<br />
The basic configuration allows the user to switch transparently between versions of the TELEMAC system via the commands v5p8 and v5p9:<br />
<pre><br />
$ v5p9<br />
Switched to TELEMAC version: v5p9<br />
</pre><br />
<br />
Version v5p9 is under development and you are encouraged not to use it though! It might be that a developer asks you to test something under version v5p9 so this is merely to make this easier.<br />
<br />
=A note about binary files=<br />
TELEMAC was traditionally run on large Unix machines which have a different way of storing binary data than the PCs used today. They are called "big endian" systems and most PCs are "little endian" machines. By convention, TELEMAC uses files in the big endian format. Luckily, the pre- and post-processors running on the PCs can output or read big endian.<br />
<br />
In terms of the TELEMAC code itself, the Intel compiler is very handy as the big or little endian type can be changed without having to recompile the whole code. This is done with the environmental variable F_UFMTENDIAN. It defaults at "big" (see /home/telemac/intel_env). This can be changed for particular applications but really you should not have to do anything.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5652General use of the TELEMAC system2008-09-18T17:26:19Z<p>Jprenaud: /* Environment set-up */</p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
TELEMAC-2D, SISYPHE, ESTEL-2D and ESTEL-3D are available. More modules could be added if necessary. Just ask.<br />
<br />
= Linux =<br />
The TELEMAC system is installed centrally on "dylan" which the Linux operating system (CentOS).<br />
'''You will need to log into dylan and use linux commands to run TELEMAC jobs'''. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this. Ask the scientific computer officer for pointers if you need some and get some training if required.<br />
<br />
"Note that because the pre- and post-prtocessors run on MS Windows, I personally encourage people to use the Linux shell only to start the TELEMAC jobs and use the MS Windows environment for editing files etc... See [[General_use_of_the_TELEMAC_system#A_note_about_ASCII_files | note below]] for a word of warning about MS Windows text editors." [[User:Jprenaud|JP Renaud]] 18:25, 18 September 2008 (BST)<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system, for instance:<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
Note that if you log in another machine (i.e. not dylan) you might get an error message about "/home/telemac" not existing or file not found. This is normal, the location probably does not exist of the other machine... Live with it or adapt the .bashrc so that the files are sourced only on dylan.<br />
<br />
= Test = <br />
<br />
Telemac-2d includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured environment. Now go and do some real work with your own files<br />
<br />
= A note about ASCII files =<br />
<br />
Windows and Linux treat end of line in ASCII files differently. This means that if you edit a steering file on Windows using MS Notepad, you might have problems running the simulation on Linux. However, it is sometimes cumbersome to use text editors on Linux via an ssh session. The solution is too use a good text editor and configure it to use Unix type end of line characters. [http://www.scintilla.org/SciTE.html Scite] is a very good text editor for the MS Windows environment.<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. However, a few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number of processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Note that dylan has 8 cores so the system is configured to run with '''8 processors as a maximum'''.<br />
<br />
Put "0" to run in scalar mode. "1" runs in parallel mode but with one processor only, so "0" and "1" should give the same results despite using different libraries.<br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. Note that this needs to be done once per login, not for each job.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster this time, maybe 30 seconds or so instead of 55 seconds. It is not a lot faster (certainly not 8 times faster!) but this is because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time. With biggers meshes and longer sinmulations, you should get a better acceleration.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre><br />
<br />
It is also possible to run TELEMAC on the University cluster, bluecrystal. This is described on another page (not finished yet but will be done soon).<br />
<br />
=Changing between versions of the TELEMAC system=<br />
The basic configuration allows the user to switch transparently between versions of the TELEMAC system via the commands v5p8 and v5p9:<br />
<pre><br />
$ v5p9<br />
Switched to TELEMAC version: v5p9<br />
</pre><br />
<br />
Version v5p9 is under development and you are encouraged not to use it though! It might be that a developer asks you to test something under version v5p9 so this is merely to make this easier.<br />
<br />
=A note about binary files=<br />
TELEMAC was traditionally run on large Unix machines which have a different way of storing binary data than the PCs used today. They are called "big endian" systems and most PCs are "little endian" machines. By convention, TELEMAC uses files in the big endian format. Luckily, the pre- and post-processors running on the PCs can output or read big endian.<br />
<br />
In terms of the TELEMAC code itself, the Intel compiler is very handy as the big or little endian type can be changed without having to recompile the whole code. This is done with the environmental variable F_UFMTENDIAN. It defaults at "big" (see /home/telemac/intel_env). This can be changed for particular applications but really you should not have to do anything.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5651General use of the TELEMAC system2008-09-18T17:25:31Z<p>Jprenaud: /* Linux */</p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
TELEMAC-2D, SISYPHE, ESTEL-2D and ESTEL-3D are available. More modules could be added if necessary. Just ask.<br />
<br />
= Linux =<br />
The TELEMAC system is installed centrally on "dylan" which the Linux operating system (CentOS).<br />
'''You will need to log into dylan and use linux commands to run TELEMAC jobs'''. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this. Ask the scientific computer officer for pointers if you need some and get some training if required.<br />
<br />
"Note that because the pre- and post-prtocessors run on MS Windows, I personally encourage people to use the Linux shell only to start the TELEMAC jobs and use the MS Windows environment for editing files etc... See [[General_use_of_the_TELEMAC_system#A_note_about_ASCII_files | note below]] for a word of warning about MS Windows text editors." [[User:Jprenaud|JP Renaud]] 18:25, 18 September 2008 (BST)<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system, for instance:<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
Note that if you log in another machine (i.e. not dylan) you might get an error message about "/home/telemac" not existing or file not found. this is normal. It does not exist of the other machine... Live with it or adapt the .bashrc so that the files are sourced only on dylan. <br />
<br />
= Test = <br />
<br />
Telemac-2d includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured environment. Now go and do some real work with your own files<br />
<br />
= A note about ASCII files =<br />
<br />
Windows and Linux treat end of line in ASCII files differently. This means that if you edit a steering file on Windows using MS Notepad, you might have problems running the simulation on Linux. However, it is sometimes cumbersome to use text editors on Linux via an ssh session. The solution is too use a good text editor and configure it to use Unix type end of line characters. [http://www.scintilla.org/SciTE.html Scite] is a very good text editor for the MS Windows environment.<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. However, a few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number of processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Note that dylan has 8 cores so the system is configured to run with '''8 processors as a maximum'''.<br />
<br />
Put "0" to run in scalar mode. "1" runs in parallel mode but with one processor only, so "0" and "1" should give the same results despite using different libraries.<br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. Note that this needs to be done once per login, not for each job.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster this time, maybe 30 seconds or so instead of 55 seconds. It is not a lot faster (certainly not 8 times faster!) but this is because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time. With biggers meshes and longer sinmulations, you should get a better acceleration.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre><br />
<br />
It is also possible to run TELEMAC on the University cluster, bluecrystal. This is described on another page (not finished yet but will be done soon).<br />
<br />
=Changing between versions of the TELEMAC system=<br />
The basic configuration allows the user to switch transparently between versions of the TELEMAC system via the commands v5p8 and v5p9:<br />
<pre><br />
$ v5p9<br />
Switched to TELEMAC version: v5p9<br />
</pre><br />
<br />
Version v5p9 is under development and you are encouraged not to use it though! It might be that a developer asks you to test something under version v5p9 so this is merely to make this easier.<br />
<br />
=A note about binary files=<br />
TELEMAC was traditionally run on large Unix machines which have a different way of storing binary data than the PCs used today. They are called "big endian" systems and most PCs are "little endian" machines. By convention, TELEMAC uses files in the big endian format. Luckily, the pre- and post-processors running on the PCs can output or read big endian.<br />
<br />
In terms of the TELEMAC code itself, the Intel compiler is very handy as the big or little endian type can be changed without having to recompile the whole code. This is done with the environmental variable F_UFMTENDIAN. It defaults at "big" (see /home/telemac/intel_env). This can be changed for particular applications but really you should not have to do anything.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5650General use of the TELEMAC system2008-09-18T17:25:06Z<p>Jprenaud: /* Linux */</p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
TELEMAC-2D, SISYPHE, ESTEL-2D and ESTEL-3D are available. More modules could be added if necessary. Just ask.<br />
<br />
= Linux =<br />
The TELEMAC system is installed centrally on "dylan" which the Linux operating system (CentOS).<br />
'''You will need to log into dylan and use linux commands to run TELEMAC jobs'''. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this. Ask the scientific computer officer for pointers if you need some and get some training if required.<br />
<br />
"Note that because the pre- and post-prtocessors run on MS Windows, I personally encourage people to use the Linux shell only to start the TELEMAC jobs and use the MS Windows environemtn for editing files etc... See [[General_use_of_the_TELEMAC_system#A_note_about_ASCII_files | note below]] for a word of warning about MS Windows text editors." [[User:Jprenaud|JP Renaud]] 18:25, 18 September 2008 (BST)<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system, for instance:<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
Note that if you log in another machine (i.e. not dylan) you might get an error message about "/home/telemac" not existing or file not found. this is normal. It does not exist of the other machine... Live with it or adapt the .bashrc so that the files are sourced only on dylan. <br />
<br />
= Test = <br />
<br />
Telemac-2d includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured environment. Now go and do some real work with your own files<br />
<br />
= A note about ASCII files =<br />
<br />
Windows and Linux treat end of line in ASCII files differently. This means that if you edit a steering file on Windows using MS Notepad, you might have problems running the simulation on Linux. However, it is sometimes cumbersome to use text editors on Linux via an ssh session. The solution is too use a good text editor and configure it to use Unix type end of line characters. [http://www.scintilla.org/SciTE.html Scite] is a very good text editor for the MS Windows environment.<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. However, a few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number of processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Note that dylan has 8 cores so the system is configured to run with '''8 processors as a maximum'''.<br />
<br />
Put "0" to run in scalar mode. "1" runs in parallel mode but with one processor only, so "0" and "1" should give the same results despite using different libraries.<br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. Note that this needs to be done once per login, not for each job.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster this time, maybe 30 seconds or so instead of 55 seconds. It is not a lot faster (certainly not 8 times faster!) but this is because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time. With biggers meshes and longer sinmulations, you should get a better acceleration.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre><br />
<br />
It is also possible to run TELEMAC on the University cluster, bluecrystal. This is described on another page (not finished yet but will be done soon).<br />
<br />
=Changing between versions of the TELEMAC system=<br />
The basic configuration allows the user to switch transparently between versions of the TELEMAC system via the commands v5p8 and v5p9:<br />
<pre><br />
$ v5p9<br />
Switched to TELEMAC version: v5p9<br />
</pre><br />
<br />
Version v5p9 is under development and you are encouraged not to use it though! It might be that a developer asks you to test something under version v5p9 so this is merely to make this easier.<br />
<br />
=A note about binary files=<br />
TELEMAC was traditionally run on large Unix machines which have a different way of storing binary data than the PCs used today. They are called "big endian" systems and most PCs are "little endian" machines. By convention, TELEMAC uses files in the big endian format. Luckily, the pre- and post-processors running on the PCs can output or read big endian.<br />
<br />
In terms of the TELEMAC code itself, the Intel compiler is very handy as the big or little endian type can be changed without having to recompile the whole code. This is done with the environmental variable F_UFMTENDIAN. It defaults at "big" (see /home/telemac/intel_env). This can be changed for particular applications but really you should not have to do anything.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5649General use of the TELEMAC system2008-09-18T17:24:32Z<p>Jprenaud: /* Linux */</p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
TELEMAC-2D, SISYPHE, ESTEL-2D and ESTEL-3D are available. More modules could be added if necessary. Just ask.<br />
<br />
= Linux =<br />
The TELEMAC system is installed centrally on "dylan" which the Linux operating system (CentOS).<br />
'''You will need to log into dylan and use linux commands to run TELEMAC jobs'''. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this. Ask the scientific computer officer for pointers if you need some and get some training if required.<br />
<br />
"Note that because the pre- and post-prtocessors run on MS Windows, I personally encourage people to use the Linux shell only to start the TELEMAC jobs and use the MS Windows environemtn for editing files etc... See [[General_use_of_the_TELEMAC_system#A_note_about_ASCII_files | note below]] for a word of warning about MS Windows text editors."[[User:Jprenaud|JP]]<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system, for instance:<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
Note that if you log in another machine (i.e. not dylan) you might get an error message about "/home/telemac" not existing or file not found. this is normal. It does not exist of the other machine... Live with it or adapt the .bashrc so that the files are sourced only on dylan. <br />
<br />
= Test = <br />
<br />
Telemac-2d includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured environment. Now go and do some real work with your own files<br />
<br />
= A note about ASCII files =<br />
<br />
Windows and Linux treat end of line in ASCII files differently. This means that if you edit a steering file on Windows using MS Notepad, you might have problems running the simulation on Linux. However, it is sometimes cumbersome to use text editors on Linux via an ssh session. The solution is too use a good text editor and configure it to use Unix type end of line characters. [http://www.scintilla.org/SciTE.html Scite] is a very good text editor for the MS Windows environment.<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. However, a few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number of processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Note that dylan has 8 cores so the system is configured to run with '''8 processors as a maximum'''.<br />
<br />
Put "0" to run in scalar mode. "1" runs in parallel mode but with one processor only, so "0" and "1" should give the same results despite using different libraries.<br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. Note that this needs to be done once per login, not for each job.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster this time, maybe 30 seconds or so instead of 55 seconds. It is not a lot faster (certainly not 8 times faster!) but this is because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time. With biggers meshes and longer sinmulations, you should get a better acceleration.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre><br />
<br />
It is also possible to run TELEMAC on the University cluster, bluecrystal. This is described on another page (not finished yet but will be done soon).<br />
<br />
=Changing between versions of the TELEMAC system=<br />
The basic configuration allows the user to switch transparently between versions of the TELEMAC system via the commands v5p8 and v5p9:<br />
<pre><br />
$ v5p9<br />
Switched to TELEMAC version: v5p9<br />
</pre><br />
<br />
Version v5p9 is under development and you are encouraged not to use it though! It might be that a developer asks you to test something under version v5p9 so this is merely to make this easier.<br />
<br />
=A note about binary files=<br />
TELEMAC was traditionally run on large Unix machines which have a different way of storing binary data than the PCs used today. They are called "big endian" systems and most PCs are "little endian" machines. By convention, TELEMAC uses files in the big endian format. Luckily, the pre- and post-processors running on the PCs can output or read big endian.<br />
<br />
In terms of the TELEMAC code itself, the Intel compiler is very handy as the big or little endian type can be changed without having to recompile the whole code. This is done with the environmental variable F_UFMTENDIAN. It defaults at "big" (see /home/telemac/intel_env). This can be changed for particular applications but really you should not have to do anything.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5648General use of the TELEMAC system2008-09-18T17:24:13Z<p>Jprenaud: /* Linux */</p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
TELEMAC-2D, SISYPHE, ESTEL-2D and ESTEL-3D are available. More modules could be added if necessary. Just ask.<br />
<br />
= Linux =<br />
The TELEMAC system is installed centrally on "dylan" which the Linux operating system (CentOS).<br />
'''You will need to log into dylan and use linux commands to run TELEMAC jobs'''. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this. Ask the scientific computer officer for pointers if you need some and get some training if required.<br />
<br />
"Note that because the pre- and post-prtocessors run on MS Windows, I personally encourage people to use the Linux shell only to start the TELEMAC jobs and use the MS Windows environemtn for editing files etc... See [[General_use_of_the_TELEMAC_system#A_note_about_ASCII_files | note below]] for a word of warning about MS Windows text editors." 18:23, 18 September 2008 (BST)<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system, for instance:<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
Note that if you log in another machine (i.e. not dylan) you might get an error message about "/home/telemac" not existing or file not found. this is normal. It does not exist of the other machine... Live with it or adapt the .bashrc so that the files are sourced only on dylan. <br />
<br />
= Test = <br />
<br />
Telemac-2d includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured environment. Now go and do some real work with your own files<br />
<br />
= A note about ASCII files =<br />
<br />
Windows and Linux treat end of line in ASCII files differently. This means that if you edit a steering file on Windows using MS Notepad, you might have problems running the simulation on Linux. However, it is sometimes cumbersome to use text editors on Linux via an ssh session. The solution is too use a good text editor and configure it to use Unix type end of line characters. [http://www.scintilla.org/SciTE.html Scite] is a very good text editor for the MS Windows environment.<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. However, a few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number of processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Note that dylan has 8 cores so the system is configured to run with '''8 processors as a maximum'''.<br />
<br />
Put "0" to run in scalar mode. "1" runs in parallel mode but with one processor only, so "0" and "1" should give the same results despite using different libraries.<br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. Note that this needs to be done once per login, not for each job.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster this time, maybe 30 seconds or so instead of 55 seconds. It is not a lot faster (certainly not 8 times faster!) but this is because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time. With biggers meshes and longer sinmulations, you should get a better acceleration.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre><br />
<br />
It is also possible to run TELEMAC on the University cluster, bluecrystal. This is described on another page (not finished yet but will be done soon).<br />
<br />
=Changing between versions of the TELEMAC system=<br />
The basic configuration allows the user to switch transparently between versions of the TELEMAC system via the commands v5p8 and v5p9:<br />
<pre><br />
$ v5p9<br />
Switched to TELEMAC version: v5p9<br />
</pre><br />
<br />
Version v5p9 is under development and you are encouraged not to use it though! It might be that a developer asks you to test something under version v5p9 so this is merely to make this easier.<br />
<br />
=A note about binary files=<br />
TELEMAC was traditionally run on large Unix machines which have a different way of storing binary data than the PCs used today. They are called "big endian" systems and most PCs are "little endian" machines. By convention, TELEMAC uses files in the big endian format. Luckily, the pre- and post-processors running on the PCs can output or read big endian.<br />
<br />
In terms of the TELEMAC code itself, the Intel compiler is very handy as the big or little endian type can be changed without having to recompile the whole code. This is done with the environmental variable F_UFMTENDIAN. It defaults at "big" (see /home/telemac/intel_env). This can be changed for particular applications but really you should not have to do anything.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5647General use of the TELEMAC system2008-09-18T17:23:45Z<p>Jprenaud: /* Linux */</p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
TELEMAC-2D, SISYPHE, ESTEL-2D and ESTEL-3D are available. More modules could be added if necessary. Just ask.<br />
<br />
= Linux =<br />
The TELEMAC system is installed centrally on "dylan" which the Linux operating system (CentOS).<br />
'''You will need to log into dylan and use linux commands to run TELEMAC jobs'''. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this. Ask the scientific computer officer for pointers if you need some and get some training if required.<br />
<br />
"Note that because the pre- and post-prtocessors run on MS Windows, I personally encourage people to use the Linux shell only to start the TELEMAC jobs and use the MS Windows environemtn for editing files etc... See [[note below]] for a word of warning about MS Windows text editors." 18:23, 18 September 2008 (BST)<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system, for instance:<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
Note that if you log in another machine (i.e. not dylan) you might get an error message about "/home/telemac" not existing or file not found. this is normal. It does not exist of the other machine... Live with it or adapt the .bashrc so that the files are sourced only on dylan. <br />
<br />
= Test = <br />
<br />
Telemac-2d includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured environment. Now go and do some real work with your own files<br />
<br />
= A note about ASCII files =<br />
<br />
Windows and Linux treat end of line in ASCII files differently. This means that if you edit a steering file on Windows using MS Notepad, you might have problems running the simulation on Linux. However, it is sometimes cumbersome to use text editors on Linux via an ssh session. The solution is too use a good text editor and configure it to use Unix type end of line characters. [http://www.scintilla.org/SciTE.html Scite] is a very good text editor for the MS Windows environment.<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. However, a few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number of processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Note that dylan has 8 cores so the system is configured to run with '''8 processors as a maximum'''.<br />
<br />
Put "0" to run in scalar mode. "1" runs in parallel mode but with one processor only, so "0" and "1" should give the same results despite using different libraries.<br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. Note that this needs to be done once per login, not for each job.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster this time, maybe 30 seconds or so instead of 55 seconds. It is not a lot faster (certainly not 8 times faster!) but this is because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time. With biggers meshes and longer sinmulations, you should get a better acceleration.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre><br />
<br />
It is also possible to run TELEMAC on the University cluster, bluecrystal. This is described on another page (not finished yet but will be done soon).<br />
<br />
=Changing between versions of the TELEMAC system=<br />
The basic configuration allows the user to switch transparently between versions of the TELEMAC system via the commands v5p8 and v5p9:<br />
<pre><br />
$ v5p9<br />
Switched to TELEMAC version: v5p9<br />
</pre><br />
<br />
Version v5p9 is under development and you are encouraged not to use it though! It might be that a developer asks you to test something under version v5p9 so this is merely to make this easier.<br />
<br />
=A note about binary files=<br />
TELEMAC was traditionally run on large Unix machines which have a different way of storing binary data than the PCs used today. They are called "big endian" systems and most PCs are "little endian" machines. By convention, TELEMAC uses files in the big endian format. Luckily, the pre- and post-processors running on the PCs can output or read big endian.<br />
<br />
In terms of the TELEMAC code itself, the Intel compiler is very handy as the big or little endian type can be changed without having to recompile the whole code. This is done with the environmental variable F_UFMTENDIAN. It defaults at "big" (see /home/telemac/intel_env). This can be changed for particular applications but really you should not have to do anything.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5646General use of the TELEMAC system2008-09-18T17:21:13Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
TELEMAC-2D, SISYPHE, ESTEL-2D and ESTEL-3D are available. More modules could be added if necessary. Just ask.<br />
<br />
= Linux =<br />
The TELEMAC system is installed centrally on "dylan" which the Linux operating system (CentOS).<br />
'''You will need to log into dylan and use linux commands to run TELEMAC jobs'''. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this. Ask the scientific computer officer for pointers if you need some and get some training if required.<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system, for instance:<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
Note that if you log in another machine (i.e. not dylan) you might get an error message about "/home/telemac" not existing or file not found. this is normal. It does not exist of the other machine... Live with it or adapt the .bashrc so that the files are sourced only on dylan. <br />
<br />
= Test = <br />
<br />
Telemac-2d includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured environment. Now go and do some real work with your own files<br />
<br />
= A note about ASCII files =<br />
<br />
Windows and Linux treat end of line in ASCII files differently. This means that if you edit a steering file on Windows using MS Notepad, you might have problems running the simulation on Linux. However, it is sometimes cumbersome to use text editors on Linux via an ssh session. The solution is too use a good text editor and configure it to use Unix type end of line characters. [http://www.scintilla.org/SciTE.html Scite] is a very good text editor for the MS Windows environment.<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. However, a few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number of processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Note that dylan has 8 cores so the system is configured to run with '''8 processors as a maximum'''.<br />
<br />
Put "0" to run in scalar mode. "1" runs in parallel mode but with one processor only, so "0" and "1" should give the same results despite using different libraries.<br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. Note that this needs to be done once per login, not for each job.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster this time, maybe 30 seconds or so instead of 55 seconds. It is not a lot faster (certainly not 8 times faster!) but this is because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time. With biggers meshes and longer sinmulations, you should get a better acceleration.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre><br />
<br />
It is also possible to run TELEMAC on the University cluster, bluecrystal. This is described on another page (not finished yet but will be done soon).<br />
<br />
=Changing between versions of the TELEMAC system=<br />
The basic configuration allows the user to switch transparently between versions of the TELEMAC system via the commands v5p8 and v5p9:<br />
<pre><br />
$ v5p9<br />
Switched to TELEMAC version: v5p9<br />
</pre><br />
<br />
Version v5p9 is under development and you are encouraged not to use it though! It might be that a developer asks you to test something under version v5p9 so this is merely to make this easier.<br />
<br />
=A note about binary files=<br />
TELEMAC was traditionally run on large Unix machines which have a different way of storing binary data than the PCs used today. They are called "big endian" systems and most PCs are "little endian" machines. By convention, TELEMAC uses files in the big endian format. Luckily, the pre- and post-processors running on the PCs can output or read big endian.<br />
<br />
In terms of the TELEMAC code itself, the Intel compiler is very handy as the big or little endian type can be changed without having to recompile the whole code. This is done with the environmental variable F_UFMTENDIAN. It defaults at "big" (see /home/telemac/intel_env). This can be changed for particular applications but really you should not have to do anything.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5645General use of the TELEMAC system2008-09-18T17:17:52Z<p>Jprenaud: /* A note about ascii and binary files */</p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
TELEMAC-2D, SISYPHE, ESTEL-2D and ESTEL-3D are available. More modules could be added if necessary. Just ask.<br />
<br />
= Linux =<br />
The TELEMAC system is installed centrally on "dylan" which the Linux operating system (CentOS).<br />
'''You will need to log into dylan and use linux commands to run TELEMAC jobs'''. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this. Ask the scientific computer officer for pointers if you need some and get some training if required.<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system, for instance:<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
Note that if you log in another machine (i.e. not dylan) you might get an error message about "/home/telemac" not existing or file not found. this is normal. It does not exist of the other machine... Live with it or adapt the .bashrc so that the files are sourced only on dylan. <br />
<br />
= Test = <br />
<br />
Telemac-2d includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured environment. Now go and do some real work with your own files<br />
<br />
= A note about ASCII and binary files =<br />
<br />
==ASCII files==<br />
Windows and Linux treat end of line in ASCII files differently. This means that if you edit a steering file on Windows using MS Notepad, you might have problems running the simulation on Linux. However, it is sometimes cumbersome to use text editors on Linux via an ssh session. The solution is too use a good text editor and configure it to use Unix type end of line characters. [http://www.scintilla.org/SciTE.html Scite] is a very good text editor for the MS Windows environment.<br />
<br />
==Binary files==<br />
TELEMAC was traditionally run on large Unix machines which have a different way of storing binary data than the PCs used today. They are called "big endian" systems and most PCs are "little endian" machines. By convention, TELEMAC uses files in the big endian format. Luckily, the pre- and post-processors running on the PCs can output or read big endian.<br />
<br />
In terms of the TELEMAC code itself, the Intel compiler is very handy as the big or little endian type can be changed without having to recompile the whole code. This is done with the environmental variable F_UFMTENDIAN. It defaults at "big" (see /home/telemac/intel_env). This can be changed for particular applications but really you should not have to do anything.<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. However, a few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number of processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Note that dylan has 8 cores so the system is configured to run with '''8 processors as a maximum'''.<br />
<br />
Put "0" to run in scalar mode. "1" runs in parallel mode but with one processor only, so "0" and "1" should give the same results despite using different libraries.<br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. Note that this needs to be done once per login, not for each job.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster this time, maybe 30 seconds or so instead of 55 seconds. It is not a lot faster (certainly not 8 times faster!) but this is because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time. With biggers meshes and longer sinmulations, you should get a better acceleration.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre><br />
<br />
It is also possible to run TELEMAC on the University cluster, bluecrystal. This is described on another page (not finished yet but will be done soon).</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5644General use of the TELEMAC system2008-09-18T17:07:27Z<p>Jprenaud: /* Parallel jobs */</p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
TELEMAC-2D, SISYPHE, ESTEL-2D and ESTEL-3D are available. More modules could be added if necessary. Just ask.<br />
<br />
= Linux =<br />
The TELEMAC system is installed centrally on "dylan" which the Linux operating system (CentOS).<br />
'''You will need to log into dylan and use linux commands to run TELEMAC jobs'''. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this. Ask the scientific computer officer for pointers if you need some and get some training if required.<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system, for instance:<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
Note that if you log in another machine (i.e. not dylan) you might get an error message about "/home/telemac" not existing or file not found. this is normal. It does not exist of the other machine... Live with it or adapt the .bashrc so that the files are sourced only on dylan. <br />
<br />
= Test = <br />
<br />
Telemac-2d includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured environment. Now go and do some real work with your own files<br />
<br />
= A note about ascii and binary files =<br />
<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. However, a few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number of processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Note that dylan has 8 cores so the system is configured to run with '''8 processors as a maximum'''.<br />
<br />
Put "0" to run in scalar mode. "1" runs in parallel mode but with one processor only, so "0" and "1" should give the same results despite using different libraries.<br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. Note that this needs to be done once per login, not for each job.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster this time, maybe 30 seconds or so instead of 55 seconds. It is not a lot faster (certainly not 8 times faster!) but this is because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time. With biggers meshes and longer sinmulations, you should get a better acceleration.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre><br />
<br />
It is also possible to run TELEMAC on the University cluster, bluecrystal. This is described on another page (not finished yet but will be done soon).</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5643General use of the TELEMAC system2008-09-18T17:06:12Z<p>Jprenaud: /* Parallel jobs */</p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
TELEMAC-2D, SISYPHE, ESTEL-2D and ESTEL-3D are available. More modules could be added if necessary. Just ask.<br />
<br />
= Linux =<br />
The TELEMAC system is installed centrally on "dylan" which the Linux operating system (CentOS).<br />
'''You will need to log into dylan and use linux commands to run TELEMAC jobs'''. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this. Ask the scientific computer officer for pointers if you need some and get some training if required.<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system, for instance:<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
Note that if you log in another machine (i.e. not dylan) you might get an error message about "/home/telemac" not existing or file not found. this is normal. It does not exist of the other machine... Live with it or adapt the .bashrc so that the files are sourced only on dylan. <br />
<br />
= Test = <br />
<br />
Telemac-2d includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured environment. Now go and do some real work with your own files<br />
<br />
= A note about ascii and binary files =<br />
<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. However, a few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number of processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Note that dylan has 8 cores so the system is configured to run with '''8 processors as a maximum'''.<br />
<br />
Put "0" to run in scalar mode. "1" runs in parallel mode but with one processor only, so "0" and "1" should give the same results despite two different libraries.<br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. Note that this needs to be done once per login, not for each job.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster this time, maybe 30 seconds or so instead of 55 seconds. It is not a lot faster (certainly not 8 times faster!) but this is because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time. With biggers meshes and longer sinmulations, you should get a better acceleration.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre></div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5642General use of the TELEMAC system2008-09-18T16:55:26Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
TELEMAC-2D, SISYPHE, ESTEL-2D and ESTEL-3D are available. More modules could be added if necessary. Just ask.<br />
<br />
= Linux =<br />
The TELEMAC system is installed centrally on "dylan" which the Linux operating system (CentOS).<br />
'''You will need to log into dylan and use linux commands to run TELEMAC jobs'''. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this. Ask the scientific computer officer for pointers if you need some and get some training if required.<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system, for instance:<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
Note that if you log in another machine (i.e. not dylan) you might get an error message about "/home/telemac" not existing or file not found. this is normal. It does not exist of the other machine... Live with it or adapt the .bashrc so that the files are sourced only on dylan. <br />
<br />
= Test = <br />
<br />
Telemac-2d includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured environment. Now go and do some real work with your own files<br />
<br />
= A note about ascii and binary files =<br />
<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. However, a few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number of processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Note that dylan has 8 processor cores so the system is configured to run with '''8 processors as a maximum'''. Put 0 to run in scalar mode. "1" runs in parallel mode but with one processor only, so "0" and "1" should gibve the ssame results despite two different libraries.<br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. This needs to be done once per login.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run teleun telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster, maybe 30 seconds or so. It is not a lot faster because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre></div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5641General use of the TELEMAC system2008-09-18T16:47:55Z<p>Jprenaud: /* Environment set-up */</p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
The TELEMAC system is installed centrally on "dylan". You will need to log into dylan to run TELEMAC jobs. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this.<br />
<br />
TELEMAC-2D, SISYPHE, ESTEL-2D and ESTEL-3D are available. More modules could be added if necessary. Just ask.<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system, for instance:<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
= Test = <br />
<br />
Telemac-ed includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured enviroment. Now go and do some real work...<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. A few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number odf processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. This needs to be done once per login.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run teleun telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster, maybe 30 seconds or so. It is not a lot faster because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre></div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5640General use of the TELEMAC system2008-09-18T16:47:40Z<p>Jprenaud: /* Environment set-up */</p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
The TELEMAC system is installed centrally on "dylan". You will need to log into dylan to run TELEMAC jobs. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this.<br />
<br />
TELEMAC-2D, SISYPHE, ESTEL-2D and ESTEL-3D are available. More modules could be added if necessary. Just ask.<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system.<br />
<pre><br />
$ which telemac2d<br />
/home/telemac/bin/telemac2d<br />
</pre><br />
<br />
= Test = <br />
<br />
Telemac-ed includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured enviroment. Now go and do some real work...<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. A few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number odf processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. This needs to be done once per login.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run teleun telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster, maybe 30 seconds or so. It is not a lot faster because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre></div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5639General use of the TELEMAC system2008-09-18T16:46:38Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
The TELEMAC system is installed centrally on "dylan". You will need to log into dylan to run TELEMAC jobs. Therefore it helps to practice a bit in a Linux environment. The [[:category:Pragmatic Programming | Pragmatic Programming]] course might be a good place for this.<br />
<br />
TELEMAC-2D, SISYPHE, ESTEL-2D and ESTEL-3D are available. More modules could be added if necessary. Just ask.<br />
<br />
= Environment set-up =<br />
<br />
It is very easy to configure the environment to use TELEMAC as you simply have to source central files. Simply add the following lines into your .bashrc configuration file, then log-out and back in again.<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
You should then be able to "see" the Fortran compiler and the programs of the TELEMAC system.<br />
<br />
= Test = <br />
<br />
Telemac-ed includes some test cases. Copy one into your filespace and run it:<br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
If this works, you have a well configured enviroment. Now go and do some real work...<br />
<br />
= Parallel jobs =<br />
The TELEMAC is configured to run in parallel mode if requested by the user. This is actually a very simple thing to do and highly encouraged if you use large meshes and run long simulations. A few extra initial steps are required.<br />
<br />
TELEMAC uses MPI for parallel operations. MPI requires a secret word in a hidden configuration file. Simply type the following instructions to create it. Note that "somethingsecret" below should contains no spaces. <br />
<br />
<pre><br />
$ cd<br />
$ touch .mpd.conf<br />
$ chmod 600 .mpd.conf<br />
$ echo "MPD_SECRETWORD=somethingsecret " > .mpd.conf<br />
</pre><br />
<br />
Run the software once in scalar mode once to look at job duration, for instance:<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
$ cd cavity/<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
The example above should run in about 55s on dylan. Now edit cas.txt so that the line about the number odf processors looks like:<br />
<pre><br />
PARALLEL PROCESSORS = 8<br />
</pre><br />
<br />
Before you can run TELEMAC in parallel, you need to start the MPI daemon. This needs to be done once per login.<br />
<br />
<pre><br />
$ mpd &<br />
</pre><br />
<br />
Then, you can now run teleun telemac2d again:<br />
<pre><br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
It should run again, faster, maybe 30 seconds or so. It is not a lot faster because it's a silly example and splitting the mesh in 8 subdomains accounts for a large part of the computation time.<br />
<br />
Before you log out, it is a good idea to kill the MPI daemon:<br />
<pre><br />
$ mpdallexit<br />
</pre></div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5638General use of the TELEMAC system2008-09-18T16:22:34Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
<br />
This page describes the general use of the TELEMAC system in Geographical Sciences.<br />
<br />
The TELEMAC system is installed centrally on "dylan". You will need to log into dylan to run TELEMAC jobs. Therefore it helps to practice a bit in a Linux environment. The [Category:Pragmatic_Programming] course can be useful.<br />
<br />
TELEMAC-2D, SISYPHE, ESTEL-2D and ESTEL-3D are available. More modules could be added if necessary. Just ask.<br />
<br />
= Environment set-up =<br />
<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
= Test = <br />
<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/hydraulic_jump .<br />
$ cd hydraulic_jump<br />
$ telemac2d cas.txt<br />
</pre><br />
<br />
= Parallel jobs =<br />
The TELEMAC is automatically configured to run in parallel mode. To run <br />
<br />
<pre><br />
cd $HOME<br />
touch .mpd.conf<br />
chmod 600 .mpd.conf<br />
MPD_SECRETWORD="somethingsecret"<br />
</pre><br />
<br />
Run the software once in scalar mode<br />
<pre><br />
$ cp -r /home/telemac/telemac2d/tel2d_v5p8/test.gb/cavity .<br />
[ggjpr@dylan ~]$ cd cavity/<br />
[ggjpr@dylan confluence]$ telemac2d cas.txt<br />
</pre><br />
<br />
Should run in about 55s<br />
Edit cas.txt and run telemac2d again and<br />
Start the ring<br />
<pre><br />
$ mpd &<br />
$ telemac2d cas.txt<br />
</pre><br />
it should run again, faster, maybe 30s inclu<br />
<br />
when you log out, it is a good idea to kill the MPI daemon with<br />
<pre><br />
$ mpdallexit<br />
</pre></div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5637General use of the TELEMAC system2008-09-18T16:03:08Z<p>Jprenaud: /* dylan */</p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
This page<br />
<br />
= dylan =<br />
The TELEMAC system is installed centrally on dylan. TELEMAC-2D, ESTEL-2D and ESTEL-3D are available.<br />
<br />
= Environment set-up =<br />
<br />
TELEMAC system:<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
Note that with the above configuration<br />
<br />
= Parallel jobs =</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5636General use of the TELEMAC system2008-09-18T16:01:26Z<p>Jprenaud: /* Environment set-up */</p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
This page<br />
<br />
= dylan =<br />
The TELEMAC system is installed centrally on dylan.<br />
<br />
= Environment set-up =<br />
<br />
TELEMAC system:<br />
<pre><br />
# Location of the TELEMAC system<br />
SYSTEL90=/home/telemac<br />
export SYSTEL90<br />
<br />
source $SYSTEL90/intel_env<br />
source $SYSTEL90/config/systel_env<br />
</pre><br />
<br />
Note that with the above configuration<br />
<br />
= Parallel jobs =</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5635General use of the TELEMAC system2008-09-18T15:12:48Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
This page<br />
<br />
= dylan =<br />
The TELEMAC system is installed centrally on dylan.<br />
<br />
= Environment set-up =<br />
<br />
TELEMAC system:<br />
<pre><br />
source /home/telemac/configv5p8/systel_env<br />
</pre><br />
Intel Fortran90 compiler<br />
<pre><br />
source /home/telemac/intel_env<br />
</pre><br />
<br />
Note that with the above configuration<br />
<br />
= Parallel jobs =</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5634General use of the TELEMAC system2008-09-18T10:06:25Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Estel]]<br />
[[Category:Telemac]]<br />
This page<br />
<br />
= dylan =<br />
<br />
= Environment set-up =<br />
<br />
= Parallel jobs =</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=General_use_of_the_TELEMAC_system&diff=5633General use of the TELEMAC system2008-09-18T10:01:12Z<p>Jprenaud: </p>
<hr />
<div>Blah</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Estel&diff=5632Estel2008-09-18T10:00:54Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Projects]]<br />
[[Category:Estel]]<br />
<br />
This wiki contains information for both the users and developers of TELEMAC and [http://www.ggy.bris.ac.uk/research/hydrology/models/estel ESTEL].<br />
<br />
Please contribute, update and create new pages if you cannot find the information that you need. It will certainly help other people. And remember, if you write it on the wiki and not only on a bit of paper, it won't get lost!!!<br />
<br />
=User documentation=<br />
All open-access documentation about TELEMAC and ESTEL can be accessed from here.<br />
<br />
* Installation:<br />
** [[Install the TELEMAC system ]]<br />
** [[Update the TELEMAC system]]<br />
* [[General use of the TELEMAC system]]<br />
* The [[Official ESTEL Documentation]] page<br />
* Tips and tricks:<br />
<!---** [[ ESTEL-2D How To page]] ---><br />
<!---** [[ ESTEL-3D How To page]] ---><br />
** [[ Handy Tecplot Add-ons]]<br />
** [[ Examples of compiler sections in systel.ini ]]<br />
** [[ How to swap between versions of the TELEMAC system ]]<br />
** [[ How to run ESTEL in parallel ]] (network of workstations)<br />
** [[ How to run ESTEL in parallel on a cluster]] (high performance cluster)<br />
<br />
=Developer documentation=<br />
To access the [[ ESTEL:Developer_documentation | developer documentation]], you need to be registered as an '''ESTEL''' developer for this wiki. Contact [[User:Jprenaud|JP Renaud]] if you need access to this section.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Polyglot&diff=5242Polyglot2008-05-29T09:51:15Z<p>Jprenaud: /* Introduction */</p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
'''Mixed Language Programming: Mix up a quick and useful cocktail today!'''<br />
<br />
=Introduction=<br />
<br />
One of the key underling themes in this series of ''pragmatic programming'' workshops is getting things done, with a minimum of fuss and wasted effort, and this workshop on '''mixed language programming''' is no exception.<br />
<br />
When we sit down to a keyboard, we do so with a particular goal in mind. We have a task, idea or experiment and the computer is our workbench. The languages we write programes with, along with the text editors, compilers, debuggers etc. are our tools. Now some tools are better than others (e.g. Subversion is an improvment upon CVS). Some we just may have a preference for (e.g. emacs vs. vi for editing files). None are perfect, however, and all have their pros and cons. <br />
<br />
What's all this got to do with mixed language programming? you ask. Well, imagine a scenario:<br />
<br />
You sit down to your workbench. You have your goal and you ask yourself whether somebody else has written some code which will do at least part of what you want. Perhaps they've bundled it up into a nice open-source library that you can use? That way you'll save truck-loads of time. A couple of web searches later, and bingo! You've found an ideal library for the job. There's only one snag. You like programming in Fortran, and the library is written in C. Scuppered! Well, perhaps not..<br />
<br />
What are your options? You could use something not so suitable because it happens to be written in Fortran. Hmm, that doesn't sound so good. You could translate the library from C to Fortran. Hmm, that sounds like tedious and time-consuming work. Plus you'd need to understand the C, and perhaps a direct translation can't be made anyhow? This is looking like a dead-end too. It would be far better to leave the library as it is and to call the routines from your favoured language. Is that possible? Sure it is! Read on and find out how..<br />
<br />
In this workshop, we'll look at ways in which we can mix languages and in the process create a useful end product which plays to the strengths of it's components and gets you to where you want to be, without any laborious re-writes. In the first two examples we'll look at calling C code from Fortran and then calling Fortran from C. To get the code for examples, log into your preferred Linux machine and cut and paste the following into your terminal.<br />
<br />
<pre><br />
svn export http://source.ggy.bris.ac.uk/subversion-open/polyglot/trunk ./polyglot<br />
</pre><br />
<br />
= Making a Fortran wrapped C parcel =<br />
<br />
In the first example we'll call a C function from a Fortran program:<br />
<br />
<pre><br />
cd examples/example1<br />
</pre><br />
<br />
To compile the example, type:<br />
<br />
<pre><br />
make<br />
</pre><br />
<br />
and to run it, type:<br />
<br />
<pre><br />
call_c.exe<br />
</pre><br />
<br />
Tada! We've mixed our languages into a single executable and it works! Cool. Very cool. OK, so much for the magic, let's take a look inside the files. Open up '''call_c.f90'''. In this simple program, we have a character string that we pass to the C function--called '''cfunc'''--which in turn modifies the string and we can print the result. For those familiar with Fotran90, the main program is trivial enough. So, let's turn to the C code in '''func.c'''. Again this is a simple function and the syntax will be familiar to those who know some C. An interesting detail, however, is the name of the function. Note that we have called it '''cfunc_''', i.e. with a trailing underscore. Why on earth have we done that? Well, we are anticipating the 'decoration' or '''name mangling''' that the compiler will apply.<br />
<br />
We can look inside the object files using a utility called '''nm'''. First let's look inside '''call_c.o'''. On my machine I get:<br />
<br />
<pre><br />
> nm call_c.o<br />
00000000 T MAIN__<br />
U _gfortran_set_std<br />
U _gfortran_st_write<br />
U _gfortran_st_write_done<br />
U _gfortran_transfer_character<br />
U cfunc_<br />
</pre><br />
<br />
These are the '''symbols''' created by the compiler in the object file. Now let's look inside '''func.o''':<br />
<br />
<pre><br />
> nm func.o<br />
00000000 T cfunc_<br />
</pre> <br />
<br />
Note the two '''cfunc_'''s? '''They match!''' If we had not pre-decorated the name of the function in '''func.c''', we would not have got a match and we would have got a link-time error. However, we were smart and got ourselves a working executable--hurrah!<br />
<br />
A word of caution, however. Different compilers 'mangle' subroutine and function names differently, i.e. dependening upon the mix of compilers, we can't always rely on a single trailing underscore decoration. You will need to use '''nm''' to determine the exact decoration your Fortran compiler expects and to design your code so that any changes are easily accomodated. One way to do this is to include a '''define''' preprocessor macro in you C code, such as:<br />
<br />
<pre><br />
#define CFUNC cfunc_<br />
...<br />
void CFUNC(int* string_size, char* string)<br />
</pre><br />
<br />
In that way, a change of decoration can be easily, and consistently made across the whole file/library.<br />
<br />
= Turning the Parcel Inside-Out =<br />
<br />
OK let's turn our mind to working the other way 'round and call a Fortran subroutine from a C program:<br />
<br />
<pre><br />
cd ../example2<br />
</pre><br />
<br />
We can compile and run in a similar way:<br />
<br />
<pre><br />
make<br />
./call_fort.exe<br />
</pre><br />
<br />
If you look inside the two key files, '''sub.f90''' and '''call_fort.c''', you can see that we've still kept the program fairly simple, but we've introduced a few more variable types (integers, floating-point numbers and arrays) and syntactic refinements (use of preprocessor macros and 'const' and 'intent(in)' declarations).<br />
<br />
The decoration and name-mangling will be familiar to you from the last example. Note the use of the '''define''' macro in '''call_fort.c''':<br />
<br />
<pre><br />
#define FORT_SUB fort_sub_<br />
</pre><br />
<br />
The code comments in the last example touched upon the distinction between the '''pass-by-value''' default behaviour of C and the '''pass-by-reference''' adopted by Fortran. Thus, in order to dovetail the two languages, we must prevail upon our C code to use pass-by-reference. We can see this in the function prototype in '''call_fort.c''':<br />
<br />
<pre><br />
extern void FORT_SUB(const int*, const int*, float[]);<br />
</pre><br />
<br />
Here we are declaring that we will use '''pointers-to''' variables, i.e. addresseses or '''references''', as the arguments to the routine, denoted by the '''*'''s. The routine, of course, is written in Fortran, and so is expecting these references. By default, C would have taken a '''copy''' of the '''value''' of a variable and passed that. This is where the term '''pass-by-value''' comes from. (Note that a side effect of pass-by-value is that any changes are only local to a routine and so do not have an effect on the value of the variable used in the calling routine.) Note the the '''const''' modifiers match with the '''intent(in)''' attributes in '''sub.f90'''. This is an example of defensive programming. Normally, when we pass references, we run the risk that called routine could modify the values of the variables in a lasting way. This may not be what you would like, and so it would be '''unsafe'''. However, by using '''const''' and '''intent(in)''', we are saying from both sides that some values are not to be changed and so we protect ourselves.<br />
<br />
In general with mixed langauge programming, we need to be careful about mathing the variable types we pass between the languages. For example, C typically uses 4 bytes to store a '''float'''. However, Fortran may use 4 or 8 bytes to store a '''real''', depending upon the type of processor in the machine (32 ior 64 bit). We need to be careful to ensure a match, otherwise we could have all sorts errors in store realated to truncation or uninitialsed memory space. Thus in '''sub.f90''', we have limited our variables to 4 bytes:<br />
<br />
<pre><br />
integer(kind=4),intent(in) :: arg_in<br />
integer(kind=4),intent(in) :: array_size<br />
real(kind=4),dimension(array_size),intent(out) :: arg_out<br />
</pre><br />
<br />
An intersting point of difference to note between Fortran and C is that arrays are indexed differently. Firstly, Fortran gives the first element of an array the index 1, by default. C gives it an index of 0. Compare the two loops in the source code files. First for the calling C program:<br />
<br />
<pre><br />
/* initialise array to ones */<br />
for(ii=0;ii<MAXSIZE;++ii) {<br />
from_fort[ii] = 1.0;<br />
}<br />
</pre> <br />
<br />
and second for the Fortran subroutine:<br />
<br />
<pre><br />
! just set output to be equal to input<br />
do ii=1,array_size<br />
arg_out(ii) = real(arg_in)<br />
end do<br />
</pre> <br />
<br />
Things diverge further for multi-dimensional arrays. This is because arrays in C are 'row-major' and arrays in Fortran are 'column major' in their ordering. Thus for a defualt 2-dimensional array, the cell (3,7) in C would map to (8,4) in Fortran. Oh the joys of mixed languages! Thankfully, since program units are typically self-contained and we would pass arrays in their entirity (actually just the memory address of the first cell), this difference in behaviour does not cause many headaches.<br />
<br />
= The cfortran Header File Project =<br />
<br />
* [http://www-zeus.desy.de/~burow/cfortran/cfortran.html]<br />
<br />
= Calling C from Python using SWIG =<br />
<br />
'''NB You will need <code>swig</code> installed on your machine for this example. <code>swig</code> is instaled on dylan'''<br />
<br />
<pre><br />
cd ../example4<br />
</pre><br />
<br />
<pre><br />
make<br />
</pre><br />
<br />
<pre><br />
./test.py<br />
</pre><br />
<br />
Currently as per:<br />
* [http://www.swig.org/tutorial.html]<br />
<br />
Here we move from 'mixing', to more of an API arrangement.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5205Subversion2008-05-15T15:07:14Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: every time something is changed in the repository, the server logs the '''time and date''', the '''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get information about your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called "subversion" and is hosted in the "open" part of source server. You can access the repository directly by navigating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn]. Select the "subversion" project.<br />
<br />
(If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.)<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
Note that "trunk/" at the end of the URL is just a convention. Usually, subversion repositories are organised so that the latest version is in the "trunk/" and other versions are in "branches/". This is purely semantics, as far as subversion is concerned, "trunk" and "branches" are merely two folders under URL.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Some commands can also use options which are given with dashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is yours to work with so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
<br />
=Conflicts=<br />
<br />
Sometimes, a commit or an update will fail because of conflicting changes. As a rule, you should always update before a commit so the example here will show a conflict creating after an update. <br />
<br />
==Creating the conflict==<br />
Let us create a conflict:<br />
* Somebody modifies file1 by adding a line and commits (let's assume revision5)<br />
* All of you update your working copies<br />
* Person1 modifies the new line<br />
* All of you modify the same line too<br />
* Person1 commits (revision 6)<br />
* Now all of you, try to update<br />
<br />
The update does not fail but file1 is flagged with the letter "C" indicating a conflict and you will notice new files in your working copy:<br />
<pre><br />
$svn status<br />
? file1.r5<br />
? file1.r6<br />
? file1.mine<br />
C file1<br />
</pre><br />
<br />
* file1.r5 is file1 as at revision 5 (i.e. the one at your last update)<br />
* file1.r6 is file1 at revision 6 (i.e. the one that is on the repository now)<br />
* file1.mine is file1 as it was in working copy before the update<br />
* file1 contains an attempt at merging the changes<br />
<br />
==Resolving the conflict==<br />
<br />
Let's look at file1:<br />
<pre><br />
$ cat file1<br />
Added this line.<br />
<<<<<<< .mine<br />
This will create the conflict.<br />
=======<br />
This LINE will create the conflict.<br />
>>>>>>> .r6<br />
</pre><br />
<br />
Subversion uses "<<<<<<" and ">>>>>>" to show the problem(s). Your version of the problem lines is shown first (.mine) and then the version in the repository (.r6).<br />
<br />
To solve the conflict, you need to edit this file and mark it as solved. For instance, let's assume that your version was the good one (that's probably not a good assumption in normal development cycles as you are just ignoring one commit here). To resolve the conflict, one could do:<br />
<br />
<pre><br />
$ cp file1.mine file1<br />
$ svn resolved file1<br />
Resolved conflicted state of 'file1'<br />
$ svn status<br />
M file1<br />
</pre><br />
<br />
Notice that the extra file disappear when the initial file is marked as "resolved". Now you could commit your changes. But '''don't''' during the practical as all of you have resolved the conflict at the same time and this should be done only once.<br />
<br />
=Other useful commands=<br />
==move==<br />
If you rename a file or directory manually, you loose its history, this is because subversion needs to be notified that a tracked file or directory will have a new name. It is simpler to use the subversion "move" command. For instance, to rename "file2", do: <br />
<pre><br />
$ svn move file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
<br />
You notice that the new file is added and the old one deleted. You could have done this manually but the advantage of this is that the history of the new file before the new name is still available.<br />
<br />
==import==<br />
When you ask for a new repository, it is empty by default. To populate it, you can use the import command. (import is because the action is done from the server, it imports something). The syntax is:<br />
<br />
<pre><br />
$ svn import PATH URL/trunk --message "Log message."<br />
</pre><br />
<br />
* PATH is the path to the local folder (by default it ses "./", i.e. the current folder)<br />
* URL is the full URL of the repository. In the example, I also added "trunk/" at the end and the trunk would be created automatically.<br />
<br />
==mkdir and cp ==<br />
Often people ask how then can create the "branches/" directory in the repository to store some specific versions of their code. This can be done by invoking mkdir directly on the server. The syntax is:<br />
<br />
<pre><br />
$ svn mkdir URL/branches --message "Log message."<br />
</pre><br />
<br />
<br />
Then you might want to create a branch of your project, for instance to call it "version1" as you start to work on version2. branching is merely a copy so you can do it directly on the server also:<br />
<br />
<pre><br />
$ svn cp -r URL/trunk URL/branches/version1 --message "Creation of the version1 branch."<br />
</pre><br />
<br />
Then you could check out URL/branches/version1 to work on version1 rather than the trunk.<br />
==export==<br />
Sometimes, you want to get the files from the version control system but this will not be used as a working copy, for instance you are going to send the files to somebody who is not involved in the development. For instance, it is the command that was used for the [[Linux1]] and [[Linux2]] practicals.<br />
<br />
You could do a checkout and remove all the hidden ".ssh" directories manually, but the easiest to to use the "export" command. It works exactly like a checkout except that you end up with a normal local folder, not a working copy. The syntax is:<br />
<br />
<pre><br />
$ svn export URL PATH<br />
</pre><br />
<br />
==merge==<br />
When you have different branches in your project, you ight want to merge the changes from one branch to another. For instance somebody has fixed a bug in version 1 that is still present in the trunk. You might want to apply the changes done on version 1 directly on the trunk. Subversion allows you to do this and it is called a merge operation. This is really beyond the scope of this introduction but it is important to know it exists. You can refer to the [http://svnbook.red-bean.com Subversion Red Book] for more information about merging.<br />
<br />
=To go further=<br />
The [http://svnbook.red-bean.com/ Subversion Red Book] is the bible of subversion. Very recommended.<br />
<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the "Pragmatic Programming" course was useful and that you feel (at least a bit) more confident about coding on the Linux platform. Have fun.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5203Subversion2008-05-15T15:04:53Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: every time something is changed in the repository, the server logs the '''time and date''', the '''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get information about your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called "subversion" and is hosted in the "open" part of source server. You can access the repository directly by navigating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
"trunk/" at the end of the URL is just a convention. Usually, subversion repositories are organised so that the latest version is in the "trunk/" and other versions are in "branches/". This is purely semantics, as far as subversion is concerned, "trunk" and "branches" are merely two folders under URL.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Some commands can also use options which are given with dashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is yours to work with so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
<br />
=Conflicts=<br />
<br />
Sometimes, a commit or an update will fail because of conflicting changes. As a rule, you should always update before a commit so the example here will show a conflict creating after an update. <br />
<br />
==Creating the conflict==<br />
Let us create a conflict:<br />
* Somebody modifies file1 by adding a line and commits (let's assume revision5)<br />
* All of you update your working copies<br />
* Person1 modifies the new line<br />
* All of you modify the same line too<br />
* Person1 commits (revision 6)<br />
* Now all of you, try to update<br />
<br />
The update does not fail but file1 is flagged with the letter "C" indicating a conflict and you will notice new files in your working copy:<br />
<pre><br />
$svn status<br />
? file1.r5<br />
? file1.r6<br />
? file1.mine<br />
C file1<br />
</pre><br />
<br />
* file1.r5 is file1 as at revision 5 (i.e. the one at your last update)<br />
* file1.r6 is file1 at revision 6 (i.e. the one that is on the repository now)<br />
* file1.mine is file1 as it was in working copy before the update<br />
* file1 contains an attempt at merging the changes<br />
<br />
==Resolving the conflict==<br />
<br />
Let's look at file1:<br />
<pre><br />
$ cat file1<br />
Added this line.<br />
<<<<<<< .mine<br />
This will create the conflict.<br />
=======<br />
This LINE will create the conflict.<br />
>>>>>>> .r6<br />
</pre><br />
<br />
Subversion uses "<<<<<<" and ">>>>>>" to show the problem(s). Your version of the problem lines is shown first (.mine) and then the version in the repository (.r6).<br />
<br />
To solve the conflict, you need to edit this file and mark it as solved. For instance, let's assume that your version was the good one (that's probably not a good assumption in normal development cycles as you are just ignoring one commit here). To resolve the conflict, one could do:<br />
<br />
<pre><br />
$ cp file1.mine file1<br />
$ svn resolved file1<br />
Resolved conflicted state of 'file1'<br />
$ svn status<br />
M file1<br />
</pre><br />
<br />
Notice that the extra file disappear when the initial file is marked as "resolved". Now you could commit your changes. But '''don't''' during the practical as all of you have resolved the conflict at the same time and this should be done only once.<br />
<br />
=Other useful commands=<br />
==move==<br />
If you rename a file or directory manually, you loose its history, this is because subversion needs to be notified that a tracked file or directory will have a new name. It is simpler to use the subversion "move" command. For instance, to rename "file2", do: <br />
<pre><br />
$ svn move file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
<br />
You notice that the new file is added and the old one deleted. You could have done this manually but the advantage of this is that the history of the new file before the new name is still available.<br />
<br />
==import==<br />
When you ask for a new repository, it is empty by default. To populate it, you can use the import command. (import is because the action is done from the server, it imports something). The syntax is:<br />
<br />
<pre><br />
$ svn import PATH URL/trunk --message "Log message."<br />
</pre><br />
<br />
* PATH is the path to the local folder (by default it ses "./", i.e. the current folder)<br />
* URL is the full URL of the repository. In the example, I also added "trunk/" at the end and the trunk would be created automatically.<br />
<br />
==mkdir and cp ==<br />
Often people ask how then can create the "branches/" directory in the repository to store some specific versions of their code. This can be done by invoking mkdir directly on the server. The syntax is:<br />
<br />
<pre><br />
$ svn mkdir URL/branches --message "Log message."<br />
</pre><br />
<br />
<br />
Then you might want to create a branch of your project, for instance to call it "version1" as you start to work on version2. branching is merely a copy so you can do it directly on the server also:<br />
<br />
<pre><br />
$ svn cp -r URL/trunk URL/branches/version1 --message "Creation of the version1 branch."<br />
</pre><br />
<br />
Then you could check out URL/branches/version1 to work on version1 rather than the trunk.<br />
==export==<br />
Sometimes, you want to get the files from the version control system but this will not be used as a working copy, for instance you are going to send the files to somebody who is not involved in the development. For instance, it is the command that was used for the [[Linux1]] and [[Linux2]] practicals.<br />
<br />
You could do a checkout and remove all the hidden ".ssh" directories manually, but the easiest to to use the "export" command. It works exactly like a checkout except that you end up with a normal local folder, not a working copy. The syntax is:<br />
<br />
<pre><br />
$ svn export URL PATH<br />
</pre><br />
<br />
==merge==<br />
When you have different branches in your project, you ight want to merge the changes from one branch to another. For instance somebody has fixed a bug in version 1 that is still present in the trunk. You might want to apply the changes done on version 1 directly on the trunk. Subversion allows you to do this and it is called a merge operation. This is really beyond the scope of this introduction but it is important to know it exists. You can refer to the [http://svnbook.red-bean.com Subversion Red Book] for more information about merging.<br />
<br />
=To go further=<br />
The [http://svnbook.red-bean.com/ Subversion Red Book] is the bible of subversion. Very recommended.<br />
<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the "Pragmatic Programming" course was useful and that you feel (at least a bit) more confident about coding on the Linux platform. Have fun.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5202Subversion2008-05-15T15:02:49Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: every time something is changed in the repository, the server logs the '''time and date''', the '''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get information about your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called "subversion" and is hosted in the "open" part of source server. You can access the repository directly by navigating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
"trunk/" at the end of the URL is just a convention. Usually, subversion repositories are organised so that the latest version is in the "trunk/" and other versions are in "branches/". This is purely semantics, as far as subversion is concerned, "trunk" and "branches" are merely two folders under URL.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Some commands can also use options which are given with dashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is yours to work with so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
<br />
=Conflicts=<br />
<br />
Sometimes, a commit or an update will fail because of conflicting changes. As a rule, you should always update before a commit so the example here will show a conflict creating after an update. <br />
<br />
==Creating the conflict==<br />
Let us create a conflict:<br />
* Somebody modifies file1 by adding a line and commits (let's assume revision5)<br />
* All of you update your working copies<br />
* Person1 modifies the new line<br />
* All of you modify the same line too<br />
* Person1 commits (revision 6)<br />
* Now all of you, try to update<br />
<br />
The update does not fail but file1 is flagged with the letter "C" indicating a conflict and you will notice new files in your working copy:<br />
<pre><br />
$svn status<br />
? file1.r5<br />
? file1.r6<br />
? file1.mine<br />
C file1<br />
</pre><br />
<br />
* file1.r5 is file1 as at revision 5 (i.e. the one at your last update)<br />
* file1.r6 is file1 at revision 6 (i.e. the one that is on the repository now)<br />
* file1.mine is file1 as it was in working copy before the update<br />
* file1 contains an attempt at merging the changes<br />
<br />
Let's look at file1:<br />
<pre><br />
$ cat file1<br />
Added this line.<br />
<<<<<<< .mine<br />
This will create the conflict.<br />
=======<br />
This LINE will create the conflict.<br />
>>>>>>> .r6<br />
</pre><br />
<br />
Subversion uses "<<<<<<" and ">>>>>>" to show the problem(s). Your version of the problem lines is shown first (.mine) and then the version in the repository (.r6).<br />
<br />
To solve the conflict, you need to edit this file and mark it as solved. For instance, let's assume that your version was the good one (that's probably not a good assumption in normal development cycles as you are just ignoring one commit here). To resolve the conflict, one could do:<br />
<br />
<pre><br />
$ cp file1.mine file1<br />
$ svn resolved file1<br />
Resolved conflicted state of 'file1'<br />
$ svn status<br />
M file1<br />
</pre><br />
<br />
Now you could commit your changes. But '''don't''' during the practical as all of you have resolved the conflict at the same time and this should be done only once.<br />
<br />
=Other useful commands=<br />
==move==<br />
If you rename a file or directory manually, you loose its history, this is because subversion needs to be notified that a tracked file or directory will have a new name. It is simpler to use the subversion "move" command. For instance, to rename "file2", do: <br />
<pre><br />
$ svn move file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
<br />
You notice that the new file is added and the old one deleted. You could have done this manually but the advantage of this is that the history of the new file before the new name is still available.<br />
<br />
==import==<br />
When you ask for a new repository, it is empty by default. To populate it, you can use the import command. (import is because the action is done from the server, it imports something). The syntax is:<br />
<br />
<pre><br />
$ svn import PATH URL/trunk --message "Log message."<br />
</pre><br />
<br />
* PATH is the path to the local folder (by default it ses "./", i.e. the current folder)<br />
* URL is the full URL of the repository. In the example, I also added "trunk/" at the end and the trunk would be created automatically.<br />
<br />
==mkdir and cp ==<br />
Often people ask how then can create the "branches/" directory in the repository to store some specific versions of their code. This can be done by invoking mkdir directly on the server. The syntax is:<br />
<br />
<pre><br />
$ svn mkdir URL/branches --message "Log message."<br />
</pre><br />
<br />
<br />
Then you might want to create a branch of your project, for instance to call it "version1" as you start to work on version2. branching is merely a copy so you can do it directly on the server also:<br />
<br />
<pre><br />
$ svn cp -r URL/trunk URL/branches/version1 --message "Creation of the version1 branch."<br />
</pre><br />
<br />
Then you could check out URL/branches/version1 to work on version1 rather than the trunk.<br />
==export==<br />
Sometimes, you want to get the files from the version control system but this will not be used as a working copy, for instance you are going to send the files to somebody who is not involved in the development. For instance, it is the command that was used for the [[Linux1]] and [[Linux2]] practicals.<br />
<br />
You could do a checkout and remove all the hidden ".ssh" directories manually, but the easiest to to use the "export" command. It works exactly like a checkout except that you end up with a normal local folder, not a working copy. The syntax is:<br />
<br />
<pre><br />
$ svn export URL PATH<br />
</pre><br />
<br />
==merge==<br />
When you have different branches in your project, you ight want to merge the changes from one branch to another. For instance somebody has fixed a bug in version 1 that is still present in the trunk. You might want to apply the changes done on version 1 directly on the trunk. Subversion allows you to do this and it is called a merge operation. This is really beyond the scope of this introduction but it is important to know it exists. You can refer to the [http://svnbook.red-bean.com Subversion Red Book] for more information about merging.<br />
<br />
=To go further=<br />
The [http://svnbook.red-bean.com/ Subversion Red Book] is the bible of subversion. Very recommended.<br />
<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the "Pragmatic Programming" course was useful and that you feel (at least a bit) more confident about coding on the Linux platform. Have fun.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5201Subversion2008-05-15T14:55:29Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: every time something is changed in the repository, the server logs the '''time and date''', the '''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get information about your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called "subversion" and is hosted in the "open" part of source server. You can access the repository directly by navigating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
"trunk/" at the end of the URL is just a convention. Usually, subversion repositories are organised so that the latest version is in the "trunk/" and other versions are in "branches/". This is purely semantics, as far as subversion is concerned, "trunk" and "branches" are merely two folders under URL.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Some commands can also use options which are given with dashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is yours to work with so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
=Other useful commands=<br />
==move==<br />
If you rename a file or directory manually, you loose its history, this is because subversion needs to be notified that a tracked file or directory will have a new name. It is simpler to use the subversion "move" command. For instance, to rename "file2", do: <br />
<pre><br />
$ svn move file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
<br />
You notice that the new file is added and the old one deleted. You could have done this manually but the advantage of this is that the history of the new file before the new name is still available.<br />
<br />
==import==<br />
When you ask for a new repository, it is empty by default. To populate it, you can use the import command. (import is because the action is done from the server, it imports something). The syntax is:<br />
<br />
<pre><br />
$ svn import PATH URL/trunk --message "Log message."<br />
</pre><br />
<br />
* PATH is the path to the local folder (by default it ses "./", i.e. the current folder)<br />
* URL is the full URL of the repository. In the example, I also added "trunk/" at the end and the trunk would be created automatically.<br />
<br />
==mkdir and cp ==<br />
Often people ask how then can create the "branches/" directory in the repository to store some specific versions of their code. This can be done by invoking mkdir directly on the server. The syntax is:<br />
<br />
<pre><br />
$ svn mkdir URL/branches --message "Log message."<br />
</pre><br />
<br />
<br />
Then you might want to create a branch of your project, for instance to call it "version1" as you start to work on version2. branching is merely a copy so you can do it directly on the server also:<br />
<br />
<pre><br />
$ svn cp -r URL/trunk URL/branches/version1 --message "Creation of the version1 branch."<br />
</pre><br />
<br />
Then you could check out URL/branches/version1 to work on version1 rather than the trunk.<br />
==export==<br />
Sometimes, you want to get the files from the version control system but this will not be used as a working copy, for instance you are going to send the files to somebody who is not involved in the development. For instance, it is the command that was used for the [[Linux1]] and [[Linux2]] practicals.<br />
<br />
You could do a checkout and remove all the hidden ".ssh" directories manually, but the easiest to to use the "export" command. It works exactly like a checkout except that you end up with a normal local folder, not a working copy. The syntax is:<br />
<br />
<pre><br />
$ svn export URL PATH<br />
</pre><br />
<br />
==merge==<br />
When you have different branches in your project, you ight want to merge the changes from one branch to another. For instance somebody has fixed a bug in version 1 that is still present in the trunk. You might want to apply the changes done on version 1 directly on the trunk. Subversion allows you to do this and it is called a merge operation. This is really beyond the scope of this introduction but it is important to know it exists. You can refer to the [http://svnbook.red-bean.com Subversion Red Book] for more information about merging.<br />
<br />
=To go further=<br />
The [http://svnbook.red-bean.com/ Subversion Red Book] is the bible of subversion. Very recommended.<br />
<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the "Pragmatic Programming" course was useful and that you feel (at least a bit) more confident about coding on the Linux platform. Have fun.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5200Subversion2008-05-15T14:52:02Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get information about your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by navigating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
"trunk/" at the end of the URL is just a convention. usually, subversion repositories are organised so that the latest version is in the "trunk/" and other versions are in "branches/". This is purely semantics, as far as subversion is concerned, "trunk" and "branches" are merely two folders under URL.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme commands can also use options which are given with dashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is yours to work with so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
=Other useful commands=<br />
==move==<br />
If you rename a file or directory manually, you loose its history, this is because subversion needs to be notified that a tracked file or directory will have a new name. It is simpler to use the subversion "move" command. For instance, to rename "file2", do: <br />
<pre><br />
$ svn move file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
<br />
You notice that the new file is added and the old one deleted. You could have done this manually but the advantage of this is that the history of the new file before the new name is still available.<br />
<br />
==import==<br />
When you ask for a new repository, it is empty by default. To populate it, you can use the import command. (import is because the action is done from the server, it imports something). The syntax is:<br />
<br />
<pre><br />
$ svn import PATH URL/trunk --message "Log message."<br />
</pre><br />
<br />
* PATH is the path to the local folder (by default it ses "./", i.e. the current folder)<br />
* URL is the full URL of the repository. In the example, I also added "trunk/" at the end and the trunk would be created automatically.<br />
<br />
==mkdir and cp ==<br />
Often people ask how then can create the "branches/" directory in the repository to store some specific versions of their code. This can be done by invoking mkdir directly on the server. The syntax is:<br />
<br />
<pre><br />
$ svn mkdir URL/branches --message "Log message."<br />
</pre><br />
<br />
<br />
Then you might want to create a branch of your project, for instance to call it "version1" as you start to work on version2. branching is merely a copy so you can do it directly on the server also:<br />
<br />
<pre><br />
$ svn cp -r URL/trunk URL/branches/version1 --message "Creation of the version1 branch."<br />
</pre><br />
<br />
Then you could check out URL/branches/version1 to work on version1 rather than the trunk.<br />
==export==<br />
Sometimes, you want to get the files from the version control system but this will not be used as a working copy, for instance you are going to send the files to somebody who is not involved in the development. For instance, it is the command that was used for the [[Linux1]] and [[Linux2]] practicals.<br />
<br />
You could do a checkout and remove all the hidden ".ssh" directories manually, but the easiest to to use the "export" command. It works exactly like a checkout except that you end up with a normal local folder, not a working copy. The syntax is:<br />
<br />
<pre><br />
$ svn export URL PATH<br />
</pre><br />
<br />
==merge==<br />
When you have different branches in your project, you ight want to merge the changes from one branch to another. For instance somebody has fixed a bug in version 1 that is still present in the trunk. You might want to apply the changes done on version 1 directly on the trunk. Subversion allows you to do this and it is called a merge operation. This is really beyond the scope of this introduction but it is important to know it exists. You can refer to the [http://svnbook.red-bean.com Subversion Red Book] for more information about merging.<br />
<br />
=To go further=<br />
The [http://svnbook.red-bean.com/ Subversion Red Book] is the bible of subversion. Very recommended.<br />
<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the "Pragmatic Programming" course was useful and that you feel (at least a bit) more confident about coding on the Linux platform. Have fun.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5199Subversion2008-05-15T14:45:52Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
=Other useful commands=<br />
==move==<br />
If you rename a file or directory manually, you loose its history, this is because subversion needs to be notified that a tracked file or directory will have a new name. It is simpler to use the subversion "move" command. For instance, to rename "file2", do: <br />
<pre><br />
$ svn move file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
<br />
You notice that the new file is added and the old one deleted. You could have done this manually but the advantage of this is that the history of the new file before the new name is still available.<br />
<br />
==import==<br />
When you ask for a new repository, it is empty by default. To populate it, you can use the import command. (import is because the action is done from the server, it imports something). The syntax is:<br />
<br />
<pre><br />
$ svn import PATH URL/trunk --message "Log message."<br />
</pre><br />
<br />
* PATH is the path to the local folder (by default it ses "./", i.e. the current folder)<br />
* URL is the full URL of the repository. In the example, I also added "trunk/" at the end and the trunk would be created automatically.<br />
<br />
==mkdir==<br />
Often people ask how then can create the "branches/" directory in the repository to store some specific versions of their code. This can be done by invoking mkdir directly on the server. The syntax is:<br />
<br />
<pre><br />
$ svn mkdir URL/branches --message "Log message."<br />
</pre><br />
<br />
==export==<br />
Sometimes, you want to get the files from the version control system but this will not be used as a working copy, for instance you are going to send the files to somebody who is not involved in the development. For instance, it is the command that was used for the [[Linux1]] and [[Linux2]] practicals.<br />
<br />
You could do a checkout and remove all the hidden ".ssh" directories manually, but the easiest to to use the "export" command. It works exactly like a checkout except that you end up with a normal local folder, not a working copy. The syntax is:<br />
<br />
<pre><br />
$ svn export URL PATH<br />
</pre><br />
<br />
==merge==<br />
When you have different branches in your project, you ight want to merge the changes from one branch to another. For instance somebody has fixed a bug in version 1 that is still present in the trunk. You might want to apply the changes done on version 1 directly on the trunk. Subversion allows you to do this and it is called a merge operation. This is really beyond the scope of this introduction but it is important to know it exists. You can refer to the [http://svnbook.red-bean.com Subversion Red Book] for more information about merging.<br />
<br />
=To go further=<br />
The [http://svnbook.red-bean.com/ Subversion Red Book] is the bible of subversion. Very recommended.<br />
<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the "Pragmatic Programming" course was useful and that you feel (at least a bit) more confident about coding on the Linux platform. Have fun.</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5198Subversion2008-05-15T14:43:50Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
=Other useful commands=<br />
==move==<br />
If you rename a file or directory manually, you loose its history, this is because subversion needs to be notified that a tracked file or directory will have a new name. It is simpler to use the subversion "move" command. For instance, to rename "file2", do: <br />
<pre><br />
$ svn move file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
<br />
You notice that the new file is added and the old one deleted. You could have done this manually but the advantage of this is that the history of the new file before the new name is still available.<br />
<br />
==import==<br />
When you ask for a new repository, it is empty by default. To populate it, you can use the import command. (import is because the action is done from the server, it imports something). The syntax is:<br />
<br />
<pre><br />
$ svn import PATH URL/trunk --message "Log message."<br />
</pre><br />
<br />
* PATH is the path to the local folder (by default it ses "./", i.e. the current folder)<br />
* URL is the full URL of the repository. In the example, I also added "trunk/" at the end and the trunk would be created automatically.<br />
<br />
==mkdir==<br />
Often people ask how then can create the "branches/" directory in the repository to store some specific versions of their code. This can be done by invoking mkdir directly on the server. The syntax is:<br />
<br />
<pre><br />
$ svn mkdir URL/branches --message "Log message."<br />
</pre><br />
<br />
==export==<br />
Sometimes, you want to get the files from the version control system but this will not be used as a working copy, for instance you are going to send the files to somebody who is not involved in the development. For instance, it is the command that was used for the [[Linux1]] and [[Linux2]] practicals.<br />
<br />
You could do a checkout and remove all the hidden ".ssh" directories manually, but the easiest to to use the "export" command. It works exactly like a checkout except that you end up with a normal local folder, not a working copy. The syntax is:<br />
<br />
<pre><br />
$ svn export URL PATH<br />
</pre><br />
<br />
==merge==<br />
When you have different branches in your project, you ight want to merge the changes from one branch to another. For instance somebody has fixed a bug in version 1 that is still present in the trunk. You might want to apply the changes done on version 1 directly on the trunk. Subversion allows you to do this and it is called a merge operation. This is really beyond the scope of this introduction but it is important to know it exists. You can refer to the [http://svnbook.red-bean.com Subversion Red Book] for more information about merging.<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5197Subversion2008-05-15T14:43:15Z<p>Jprenaud: /* To go further */</p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
=Other useful commands=<br />
==move==<br />
If you rename a file or directory manually, you loose its history, this is because subversion needs to be notified that a tracked file or directory will have a new name. It is simpler to use the subversion "move" command. For instance, to rename "file2", do: <br />
<pre><br />
$ svn move file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
<br />
You notice that the new file is added and the old one deleted. You could have done this manually but the advantage of this is that the history of the new file before the new name is still available.<br />
<br />
==import==<br />
When you ask for a new repository, it is empty by default. To populate it, you can use the import command. (import is because the action is done from the server, it imports something). The syntax is:<br />
<br />
<pre><br />
$ svn import PATH URL/trunk --message "Log message."<br />
</pre><br />
<br />
* PATH is the path to the local folder (by default it ses "./", i.e. the current folder)<br />
* URL is the full URL of the repository. In the example, I also added "trunk/" at the end and the trunk would be created automatically.<br />
<br />
==mkdir==<br />
Often people ask how then can create the "branches/" directory in the repository to store some specific versions of their code. This can be done by invoking mkdir directly on the server. The syntax is:<br />
<br />
<pre><br />
$ svn mkdir URL/branches --message "Log message."<br />
</pre><br />
<br />
==export==<br />
Sometimes, you want to get the files from the version control system but this will not be used as a working copy, for instance you are going to send the files to somebody who is not involved in the development. For instance, it is the command that was used for the [[Linux1]] and [[Linux2]] practicals.<br />
<br />
You could do a checkout and remove all the hidden ".ssh" directories manually, but the easiest to to use the "export" command. It works exactly like a checkout except that you end up with a normal local folder, not a working copy. The syntax is:<br />
<br />
<pre><br />
$ svn export URL PATH<br />
</pre><br />
<br />
=To go further=<br />
The subversion bible is the [http://svnbook.red-bean.com/ Subversion Red Book]. It is very very thorough. Highly recommended.<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5196Subversion2008-05-15T14:42:06Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
=Other useful commands=<br />
==move==<br />
If you rename a file or directory manually, you loose its history, this is because subversion needs to be notified that a tracked file or directory will have a new name. It is simpler to use the subversion "move" command. For instance, to rename "file2", do: <br />
<pre><br />
$ svn move file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
<br />
You notice that the new file is added and the old one deleted. You could have done this manually but the advantage of this is that the history of the new file before the new name is still available.<br />
<br />
==import==<br />
When you ask for a new repository, it is empty by default. To populate it, you can use the import command. (import is because the action is done from the server, it imports something). The syntax is:<br />
<br />
<pre><br />
$ svn import PATH URL/trunk --message "Log message."<br />
</pre><br />
<br />
* PATH is the path to the local folder (by default it ses "./", i.e. the current folder)<br />
* URL is the full URL of the repository. In the example, I also added "trunk/" at the end and the trunk would be created automatically.<br />
<br />
==mkdir==<br />
Often people ask how then can create the "branches/" directory in the repository to store some specific versions of their code. This can be done by invoking mkdir directly on the server. The syntax is:<br />
<br />
<pre><br />
$ svn mkdir URL/branches --message "Log message."<br />
</pre><br />
<br />
==export==<br />
Sometimes, you want to get the files from the version control system but this will not be used as a working copy, for instance you are going to send the files to somebody who is not involved in the development. For instance, it is the command that was used for the [[Linux1]] and [[Linux2]] practicals.<br />
<br />
You could do a checkout and remove all the hidden ".ssh" directories manually, but the easiest to to use the "export" command. It works exactly like a checkout except that you end up with a normal local folder, not a working copy. The syntax is:<br />
<br />
<pre><br />
$ svn export URL PATH<br />
</pre><br />
<br />
==merge==<br />
When you have different branches in your project, you ight want to merge the changes from one branch to another. For instance somebody has fixed a bug in version 1 that is still present in the trunk. You might want to apply the changes done on version 1 directly on the trunk. Subversion allows you to do this and it is called a merge operation. This is really beyond the scope of this introduction but it is important to know it exists. You can refer to the [http://svnbook.red-bean.com Subversion Red Book] for more information about merging.<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5195Subversion2008-05-15T14:40:13Z<p>Jprenaud: /* Other useful commands */</p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
<br />
=Other useful commands=<br />
==move==<br />
If you rename a file or directory manually, you loose its history, this is because subversion needs to be notified that a tracked file or directory will have a new name. It is simpler to use the subversion "move" command. For instance, to rename "file2", do: <br />
<pre><br />
$ svn move file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
<br />
You notice that the new file is added and the old one deleted. You could have done this manually but the advantage of this is that the history of the new file before the new name is still available.<br />
<br />
==import==<br />
When you ask for a new repository, it is empty by default. To populate it, you can use the import command. (import is because the action is done from the server, it imports something). The syntax is:<br />
<br />
<pre><br />
$ svn import PATH URL/trunk --message "Log message."<br />
</pre><br />
<br />
* PATH is the path to the local folder (by default it ses "./", i.e. the current folder)<br />
* URL is the full URL of the repository. In the example, I also added "trunk/" at the end and the trunk would be created automatically.<br />
<br />
==mkdir==<br />
Often people ask how then can create the "branches/" directory in the repository to store some specific versions of their code. This can be done by invoking mkdir directly on the server. The syntax is:<br />
<br />
<pre><br />
$ svn mkdir URL/branches --message "Log message."<br />
</pre><br />
<br />
==export==<br />
Sometimes, you want to get the files from the version control system but this will not be used as a working copy, for instance you are going to send the files to somebody who is not involved in the development. For instance, it is the command that was used for the [[Linux1]] and [[Linux2]] practicals.<br />
<br />
You could do a checkout and remove all the hidden ".ssh" directories manually, but the easiest to to use the "export" command. It works exactly like a checkout except that you end up with a normal local folder, not a working copy. The syntax is:<br />
<br />
<pre><br />
$ svn export URL PATH<br />
</pre><br />
<br />
<br />
<br />
=Other useful commands=<br />
==move==<br />
Rename<br />
<pre><br />
$ svn mv file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
==import==<br />
==mkdir==<br />
==export==<br />
==merge==<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5194Subversion2008-05-15T14:39:02Z<p>Jprenaud: /* Other useful commands */</p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
<br />
=Other useful commands=<br />
==move==<br />
If you rename a file or directory manually, you loose its history, this is because subversion needs to be notified that a tracked file or directory will have a new name. It is simpler to use the subversion "move" command. For instance, to rename "file2", do: <br />
<pre><br />
$ svn move file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
<br />
You notice that the new file is added and the old one deleted. You could have done this manually but the advantage of this is that the history of the new file before the new name is still available.<br />
<br />
==import==<br />
When you ask for a new repository, it is empty by default. To populate it, you can use the import command. (import is because the action is done from the server, it imports something). The syntax is:<br />
<br />
<pre><br />
$ svn import PATH URL/trunk --message "Log message."<br />
</pre><br />
<br />
* PATH is the path to the local folder (by default it ses "./", i.e. the current folder)<br />
* URL is the full URL of the repository. In the example, I also added "trunk/" at the end and the trunk would be created automatically.<br />
<br />
==mkdir==<br />
Often people ask how then can create the "branches/" directory in the repository to store some specific versions of their code. This can be done by invoking mkdir directly on the server. The syntax is:<br />
<br />
<pre><br />
$ svn mkdir URL/branches --message "Log message."<br />
</pre><br />
<br />
==export==<br />
Sometimes, you want to get the files from the version control system but this will not be used as a working copy, for instance you are going to send the files to somebody who is not involved in the development. For instance, it is the command that was used for the [[Linux1]] and [[Linux2]] practicals.<br />
<br />
You could do a checkout and remove all the hidden ".ssh" directories manually, but the easiest to to use the "export" command. It works exactly like a checkout except that you end up with a normal local folder, not a working copy. The syntax is:<br />
<br />
<pre><br />
$ svn export URL PATH<br />
</pre><br />
<br />
==merge==<br />
When you have different branches in your project, you ight want to merge the changes from one branch to another. For instance somebody has fixed a bug in version 1 that is still present in the trunk. You might want to apply the changes done on version 1 directly on the trunk. Subversion allows you to do this and it is called a merge operation. This is really beyond the scope of this introduction but it is important to know it exists. You can refer to the [http://svnbook.red-bean.com Subversion Red Book] for more information about merging.<br />
<br />
=Other useful commands=<br />
==move==<br />
Rename<br />
<pre><br />
$ svn mv file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
==import==<br />
==mkdir==<br />
==export==<br />
==merge==<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5193Subversion2008-05-15T14:23:37Z<p>Jprenaud: /* Creating the conflict */</p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
<br />
==Creating the conflict==<br />
Let us create a conflict:<br />
* Somebody modifies file1 by adding a line and commits (let's assume revision5)<br />
* All of you update your working copies<br />
* Person1 modifies the new line<br />
* All of you modify the same line too<br />
* Person1 commits (revision 6)<br />
* Now all of you, try to update<br />
<br />
The update does not fail but file1 is flagged with the letter "C" indicating a conflict and you will notice new files in your working copy:<br />
<pre><br />
$svn status<br />
? file1.r5<br />
? file1.r6<br />
? file1.mine<br />
C file1<br />
</pre><br />
<br />
* file1.r5 is file1 as at revision 5 (i.e. the one at your last update)<br />
* file1.r6 is file1 at revision 6 (i.e. the one that is on the repository now)<br />
* file1.mine is file1 as it was in working copy before the update<br />
* file1 contains an attempt at merging the changes<br />
<br />
Let's look at file1:<br />
<pre><br />
$ cat file1<br />
Added this line.<br />
<<<<<<< .mine<br />
This will create the conflict.<br />
=======<br />
This LINE will create the conflict.<br />
>>>>>>> .r6<br />
</pre><br />
<br />
Subversion uses "<<<<<<" and ">>>>>>" to show the problem(s). Your version of the problem lines is shown first (.mine) and then the version in the repository (.r6).<br />
<br />
To solve the conflict, you need to edit this file and mark it as solved. For instance, let's assume that your version was the good one (that's probably not a good assumption in normal development cycles as you are just ignoring one commit here). To resolve the conflict, one could do:<br />
<br />
<pre><br />
$ cp file1.mine file1<br />
$ svn resolved file1<br />
Resolved conflicted state of 'file1'<br />
$ svn status<br />
M file1<br />
</pre><br />
<br />
Now you could commit your changes. But '''don't''' during the practical as all of you have resolved the conflict at the same time and this should be done only once.<br />
<br />
=Other useful commands=<br />
==move==<br />
Rename<br />
<pre><br />
$ svn mv file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
==import==<br />
==mkdir==<br />
==export==<br />
==merge==<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5192Subversion2008-05-14T15:52:40Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
<br />
=conflicts=<br />
There are two types of conflicts. Conflicts that occur when you try to commit (i.e. the repository has changed since your last update) and those who happen when you update. The first type is nasty because the commit simply fails saying the working copy is out of date. The second type is easier because, although the conflict still happens, it is flagged properly and can be resolved more easily. A general rule is to always update before a commit and then only the second type of conflict happens.<br />
<br />
In this section we will create a conflict and see how it can be resolved. The word of warning is that subversion will not solve conflicts for you and often you should get in touch with the person who wrote the conflicting bit and have a chat...<br />
<br />
==Creating the conflict==<br />
Let us create a conflict:<br />
* Somebody modify file1 by adding a line.<br />
* All of you update your working copies<br />
* Person1 modifies the new line<br />
* All of you modify the same line too<br />
* Person1 commits<br />
* Now all of you, try to update<br />
<br />
Now the conflict is flagged with the letter "G" and you will notice new files in the working copy.<br />
<br />
==Resolving a conflict==<br />
<br />
=Other useful commands=<br />
==move==<br />
Rename<br />
<pre><br />
$ svn mv file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
==import==<br />
==mkdir==<br />
==export==<br />
==merge==<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5191Subversion2008-05-14T15:51:38Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
<br />
=conflicts=<br />
There are two types of conflicts. Conflicts that occur when you try to commit (i.e. the repository has changed since your last update) and those who happen when you update. The first type is nasty because the commit simply fails saying the working copy is out of date. The second type is easier because, although the conflict still happens, it is flagged properly and can be resolved more easily. A general rule is to always update before a commit and then only the second type of conflict happens.<br />
<br />
In this section we will create a conflict and see how it can be resolved. The word of warning is that subversion will not solve conflicts for you and often you should get in touch with the person who wrote the conflicting bit and have a chat...<br />
<br />
==Creating the conflict==<br />
Let us create a conflict:<br />
* Somebody modify file1 by adding a line.<br />
* All of you update your working copies<br />
* Person1 modifies the new line<br />
* All of you modify the same line too<br />
* Person1 commits<br />
* Now all of you, try to update<br />
<br />
Now the conflict is flagged with the letter "G" and you will notice new files in the working copy.<br />
<br />
==Resolving a conflict==<br />
<br />
=conflicts=<br />
In this section we will create a conflict and see how it can be resolved. The word of warning is that subversion will not solve conflicts for you and often you should get in touch with the person who wrote the conflicting bit and have a chat...<br />
<br />
there are two types of conflicts. Conflicts that occur when you try to commit (i.e. the repository has changed since your last update) and those who happen when you update. The first type is nasty because the commit simply fails saying the working copy is out of date. The second type is easier because, although the conflict still happens, it is flagged properly and can be resolved more easily. A general rule is to always update before a commit and then only the second type of conflict happens.<br />
==Creating a conflict==<br />
Let us create a conflict:<br />
* Somebody modify file1 by adding a line.<br />
* All of you update your working copies<br />
* Person1 modifies the new line<br />
* All of you modify the same line too<br />
* Person1 commits<br />
* Now all of you, try to update<br />
<br />
Now the conflict is flagged with the letter "G" and you will notice new files in the working copy.<br />
==Resolving a conflict==<br />
<br />
=Other useful commands=<br />
==move==<br />
Rename<br />
<pre><br />
$ svn mv file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
==import==<br />
==mkdir==<br />
==export==<br />
==merge==<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5190Subversion2008-05-14T15:49:31Z<p>Jprenaud: /* conflicts */</p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
=conflicts=<br />
There are two types of conflicts. Conflicts that occur when you try to commit (i.e. the repository has changed since your last update) and those who happen when you update. The first type is nasty because the commit simply fails saying the working copy is out of date. The second type is easier because, although the conflict still happens, it is flagged properly and can be resolved more easily. A general rule is to always update before a commit and then only the second type of conflict happens.<br />
<br />
In this section we will create a conflict and see how it can be resolved. The word of warning is that subversion will not solve conflicts for you and often you should get in touch with the person who wrote the conflicting bit and have a chat...<br />
<br />
==Creating the conflict==<br />
Let us create a conflict:<br />
* Somebody modify file1 by adding a line.<br />
* All of you update your working copies<br />
* Person1 modifies the new line<br />
* All of you modify the same line too<br />
* Person1 commits<br />
* Now all of you, try to update<br />
<br />
Now the conflict is flagged with the letter "G" and you will notice new files in the working copy.<br />
<br />
==Resolving a conflict==<br />
<br />
=conflicts=<br />
In this section we will create a conflict and see how it can be resolved. The word of warning is that subversion will not solve conflicts for you and often you should get in touch with the person who wrote the conflicting bit and have a chat...<br />
<br />
there are two types of conflicts. Conflicts that occur when you try to commit (i.e. the repository has changed since your last update) and those who happen when you update. The first type is nasty because the commit simply fails saying the working copy is out of date. The second type is easier because, although the conflict still happens, it is flagged properly and can be resolved more easily. A general rule is to always update before a commit and then only the second type of conflict happens.<br />
==Creating a conflict==<br />
Let us create a conflict:<br />
* Somebody modify file1 by adding a line.<br />
* All of you update your working copies<br />
* Person1 modifies the new line<br />
* All of you modify the same line too<br />
* Person1 commits<br />
* Now all of you, try to update<br />
<br />
Now the conflict is flagged with the letter "G" and you will notice new files in the working copy.<br />
==Resolving a conflict==<br />
<br />
=Other useful commands=<br />
==move==<br />
Rename<br />
<pre><br />
$ svn mv file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
==import==<br />
==mkdir==<br />
==export==<br />
==merge==<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5189Subversion2008-05-14T15:41:17Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
Standard diff syntax is used with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
<br />
<br />
=conflicts=<br />
In this section we will create a conflict and see how it can be resolved. The word of warning is that subversion will not solve conflicts for you and often you should get in touch with the person who wrote the conflicting bit and have a chat...<br />
<br />
there are two types of conflicts. Conflicts that occur when you try to commit (i.e. the repository has changed since your last update) and those who happen when you update. The first type is nasty because the commit simply fails saying the working copy is out of date. The second type is easier because, although the conflict still happens, it is flagged properly and can be resolved more easily. A general rule is to always update before a commit and then only the second type of conflict happens.<br />
==Creating a conflict==<br />
Let us create a conflict:<br />
* Somebody modify file1 by adding a line.<br />
* All of you update your working copies<br />
* Person1 modifies the new line<br />
* All of you modify the same line too<br />
* Person1 commits<br />
* Now all of you, try to update<br />
<br />
Now the conflict is flagged with the letter "G" and you will notice new files in the working copy.<br />
==Resolving a conflict==<br />
<br />
=Other useful commands=<br />
==move==<br />
Rename<br />
<pre><br />
$ svn mv file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
==import==<br />
==mkdir==<br />
==export==<br />
==merge==<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5188Subversion2008-05-14T15:38:18Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
=conflicts=<br />
In this section we will create a conflict and see how it can be resolved. The word of warning is that subversion will not solve conflicts for you and often you should get in touch with the person who wrote the conflicting bit and have a chat...<br />
<br />
there are two types of conflicts. Conflicts that occur when you try to commit (i.e. the repository has changed since your last update) and those who happen when you update. The first type is nasty because the commit simply fails saying the working copy is out of date. The second type is easier because, although the conflict still happens, it is flagged properly and can be resolved more easily. A general rule is to always update before a commit and then only the second type of conflict happens.<br />
==Creating a conflict==<br />
Let us create a conflict:<br />
* Somebody modify file1 by adding a line.<br />
* All of you update your working copies<br />
* Person1 modifies the new line<br />
* All of you modify the same line too<br />
* Person1 commits<br />
* Now all of you, try to update<br />
<br />
Now the conflict is flagged with the letter "G" and you will notice new files in the working copy.<br />
==Resolving a conflict==<br />
<br />
=Other useful commands=<br />
==move==<br />
Rename<br />
<pre><br />
$ svn mv file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
==import==<br />
==mkdir==<br />
==export==<br />
==merge==<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5187Subversion2008-05-14T15:35:35Z<p>Jprenaud: /* Resolving conflicts */</p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
=Resolving conflicts=<br />
In this section we will create a conflict and see how it can be resolved. The word of warning is that subversion will not solve conflicts for you and often you should get in touch with the person who wrote the conflicting bit and have a chat...<br />
<br />
there are two types of conflicts. Conflicts that occur when you try to commit (i.e. the repository has changed since your last update) and those who happen when you update. The first type is nasty because the commit simply fails saying the working copy is out of date. The second type is easier because, although the conflict still happens, it is flagged properly and can be resolved more easily. A general rule is to always update before a commit and then only the second type of conflict happens.<br />
<br />
Let us create a conflict:<br />
* Somebody modify file1 by adding a line.<br />
* All of you update your working copies<br />
* Person1 modifies the new line<br />
* All of you modify the same line too<br />
* Person1 commits<br />
* Now all of you, try to update<br />
<br />
Now the conflict is flagged with the letter "G" and you will notice new files in the working copy.<br />
<br />
=Resolving conflicts=<br />
In this section we will create a conflict and see how it can be resolved. The word of warning is that subversion will not solve conflicts for you and often you should get in touch with the person who wrote the conflicting bit and have a chat...<br />
<br />
there are two types of conflicts. Conflicts that occur when you try to commit (i.e. the repository has changed since your last update) and those who happen when you update. The first type is nasty because the commit simply fails saying the working copy is out of date. The second type is easier because, although the conflict still happens, it is flagged properly and can be resolved more easily. A general rule is to always update before a commit and then only the second type of conflict happens.<br />
<br />
Let us create a conflict:<br />
* Somebody modify file1 by adding a line.<br />
* All of you update your working copies<br />
* Person1 modifies the new line<br />
* All of you modify the same line too<br />
* Person1 commits<br />
* Now all of you, try to update<br />
<br />
Now the conflict is flagged with the letter "G" and you will notice new files in the working copy.<br />
<br />
=Resolving conflicts=<br />
<br />
=Other useful commands=<br />
==move==<br />
Rename<br />
<pre><br />
$ svn mv file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
==import==<br />
==mkdir==<br />
==export==<br />
==merge==<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5186Subversion2008-05-14T15:33:38Z<p>Jprenaud: /* Resolving conflicts */</p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
It uses standard diff syntax with "+" for additions and "-" for deletions.<br />
<br />
=Resolving conflicts=<br />
In this section we will create a conflict and see how it can be resolved. The word of warning is that subversion will not solve conflicts for you and often you should get in touch with the person who wrote the conflicting bit and have a chat...<br />
<br />
there are two types of conflicts. Conflicts that occur when you try to commit (i.e. the repository has changed since your last update) and those who happen when you update. The first type is nasty because the commit simply fails saying the working copy is out of date. The second type is easier because, although the conflict still happens, it is flagged properly and can be resolved more easily. A general rule is to always update before a commit and then only the second type of conflict happens.<br />
<br />
Let us create a conflict:<br />
* Somebody modify file1 by adding a line.<br />
* All of you update your working copies<br />
* Person1 modifies the new line<br />
* All of you modify the same line too<br />
* Person1 commits<br />
* Now all of you, try to update<br />
<br />
Now the conflict is flagged with the letter "G" and you will notice new files in the working copy.<br />
<br />
=Resolving conflicts=<br />
<br />
=Other useful commands=<br />
==move==<br />
Rename<br />
<pre><br />
$ svn mv file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
==import==<br />
==mkdir==<br />
==export==<br />
==merge==<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5185Subversion2008-05-14T15:20:49Z<p>Jprenaud: </p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
It uses standard diff syntax with "+" for additions and "-" for deletions.<br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
<br />
=Resolving conflicts=<br />
<br />
=Other useful commands=<br />
==move==<br />
Rename<br />
<pre><br />
$ svn mv file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
==import==<br />
==mkdir==<br />
==export==<br />
==merge==<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5184Subversion2008-05-14T15:18:57Z<p>Jprenaud: /* diff */</p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
<br />
==blame==<br />
<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
<br />
=Resolving conflicts=<br />
<br />
=Other useful commands=<br />
==move==<br />
Rename<br />
<pre><br />
$ svn mv file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
==import==<br />
==mkdir==<br />
==export==<br />
==merge==<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5183Subversion2008-05-14T15:18:13Z<p>Jprenaud: /* blame */</p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
==blame==<br />
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.<br />
<br />
<pre><br />
$ svn log file2 --revision 3<br />
------------------------------------------------------------------------<br />
r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line<br />
<br />
More things.<br />
------------------------------------------------------------------------<br />
</pre><br />
<br />
==blame==<br />
<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
<br />
=Resolving conflicts=<br />
<br />
=Other useful commands=<br />
==move==<br />
Rename<br />
<pre><br />
$ svn mv file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
==import==<br />
==mkdir==<br />
==export==<br />
==merge==<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5182Subversion2008-05-14T15:16:03Z<p>Jprenaud: /* diff */</p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
It uses standard diff type syntax with "+" to show additions and "-" to show deletions. As with log, you can also use revision numbers.<br />
<br />
==blame==<br />
<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
<br />
=Resolving conflicts=<br />
<br />
=Other useful commands=<br />
==move==<br />
Rename<br />
<pre><br />
$ svn mv file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
==import==<br />
==mkdir==<br />
==export==<br />
==merge==<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaudhttps://source.geography.bristol.ac.uk/mediawiki/index.php?title=Subversion&diff=5181Subversion2008-05-14T15:15:06Z<p>Jprenaud: /* diff */</p>
<hr />
<div>[[Category:Pragmatic Programming]]<br />
<br />
=Version control concepts=<br />
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the '''repository''' and the subversion server logs all operations happening on the repository: everytime something is changed in the repository, the server logs the '''time and date''', the ''changes''', the '''author''' as well as a '''log message'''. The server can be configured to let some people do actions that other cannot. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.<br />
<br />
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion '''client'''. Some of you might already know about some graphical subversion clients such as TortoiseSVN. This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get informationabout your '''working copy''' which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:<br />
* which files have I modified since I last synchronised with the server?<br />
* when was that file last modified?<br />
* who wrote the stupid bug at line 18 in file foo.c?<br />
* what has changed in that file?<br />
<br />
The repository that we are going to use for this practical is called subversion and is hosted in the "open" part of source server. You can access the repository directly by naviguating to [http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk]. This is not a very intuitive interface and we also provide a nicer interface called [http://source.ggy.bris.ac.uk/websvn websvn] and select the "subversion" project.<br />
<br />
If you don't have a subversion login, use [http://source.ggy.bris.ac.uk/websvn-open this link] instead, but then you will '''not''' be able to send anything to the server.<br />
<br />
Keep a websvn browser window open to check the state of the repository throughout the practical.<br />
<br />
=svn: the subversion command line client=<br />
The subversion command line client is called "svn". To execute a subversion command, simply type:<br />
<pre><br />
$ svn command arguments<br />
</pre><br />
<br />
Somme command can also use options which are given withdashes:<br />
<pre><br />
svn command arguments --option optionvalue<br />
</pre><br />
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:<br />
<pre><br />
$ svn help command<br />
</pre><br />
<br />
=Getting the content for this practical=<br />
You have used the subversion client for all the practicals in the [[:category:Pragmatic Programming | Pragmatic Programming]] course. To create a '''working copy''' of the repository type (first make sure you don't have a local folder called "subversion"):<br />
<pre><br />
$ svn checkout http://source.ggy.bris.ac.uk/subversion-open/subversion/trunk subversion<br />
A subversion/file1<br />
A subversion/file2<br />
A subversion/folder1<br />
A subversion/folder1/somefile<br />
A subversion/folder2<br />
A subversion/folder2/somefile<br />
</pre> <br />
<br />
What this command does is import the content of the URL into a new folder called subversion. The letter "A" simply means that these files have been added.<br />
<br />
The content that you saw in websvn in now in your own file space. You will also notice hidden directories called ".svn". It is '''very''' important that you do not touch these directories.<br />
<br />
=Modifying the working copy=<br />
The working copy is your to work in so go ahead and modify some things. To simplify the practical, only modify the file named after you to start with (in the wiki, file2 was modified). To see what files you have modified, you ask the client for the status of your working copy:<br />
<pre><br />
$ svn status<br />
M file2<br />
</pre><br />
<br />
The status shows the letter "M" for file2, indicating it has been modified.<br />
<br />
Note that this status only shows the things that have changed in '''your''' working copy. Not the changes made by others of on the server.<br />
<br />
You can also add a new file. Name the new file after your name and add a suffix. "newfile" is used in the wiki:<br />
<br />
<pre><br />
$ touch newfile<br />
$ svn status<br />
? newfile<br />
</pre><br />
<br />
The interogation mark shows that the subversion client does not know what to do with the new file. By default, svn will ignore new files. To indicate that a new file should be versionned, use the add command:<br />
<pre><br />
$ svn add newfile<br />
A newfile<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
Note that the letter "A" is used showing an addition.<br />
<br />
The same things happen for deletions. Let's try to delete file1 for instance:<br />
<pre><br />
$ rm -f file1<br />
$ svn status<br />
! file1<br />
M file2<br />
A newfile<br />
$ svn delete file1<br />
D file1<br />
$ svn status<br />
D file1<br />
M file2<br />
</pre><br />
<br />
The letter "D" is used for deletions.<br />
<br />
Subversion allows you to revert changes when you have made an error. Let's assume that file1 was deleted by error, you can get it back with:<br />
<br />
<pre><br />
$ svn revert file1<br />
Reverted 'file1'<br />
$ svn status<br />
M file2<br />
A newfile<br />
</pre><br />
<br />
The next step is to send all these changes to the server. To avoid conflicts at this stage, make sure that you have only modified files containing your name (although this wiki page uses file2 and newfile). If you have modified anything else, revert the relevant changes.<br />
<br />
=Sending changes to the repository=<br />
<br />
Sending changes to the repository is called a '''commit'''. The syntax to commit your changes is:<br />
<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
Sending file2<br />
Adding newfile<br />
Transmitting file data ..<br />
Committed revision 2.<br />
</pre><br />
<br />
You might have noticed the revision number. You should all get different revision numbers are your commits will be done one after the other. Because you have all worked on separate files, there is no risk of conflicts and subversion will happily combine all your changes together. Have a look in websvn (refresh the page) to see the state of the repository.<br />
<br />
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then popup to be used to write the commit and by saving-exiting, the commit will be done. Note that svn use the editor stored in the EDITOR environment variable and often defaults to vi if this variable is undefined. So if you are an emacs fan, set the variable first:<br />
<br />
<pre><br />
$ export EDITOR=emacs<br />
</pre><br />
<br />
At this stage in the practical you and others have sent changes to the server. To bring these changes back to your working copy, you need to update it.<br />
<br />
=Updating your working copy=<br />
<br />
To update your working copy, simply run:<br />
<pre><br />
$ svn commit [--message "Log message."] [--username subversionlogin]<br />
... <- list of files that have been added/modified<br />
At revision 8.<br />
</pre><br />
<br />
Again, because you have all worked on separate files, there is no risk of conflicts and subversion should fetch all the changes without problem.<br />
Your working copy contains now all the bits and pieces chenged by other people. A lot neater that emailing batches files etc, no?<br />
<br />
status, commit and update will probably be your most widely used commands:<br />
* update regularly to bring other people's work<br />
* status to make sure all is well<br />
* commit<br />
<br />
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.<br />
<br />
=Investigating changes=<br />
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.<br />
<br />
==log==<br />
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:<br />
<pre><br />
$ svn log --verbose<br />
------------------------------------------------------------------------<br />
r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line<br />
Changed paths:<br />
M /trunk/file2<br />
A /trunk/newfile<br />
<br />
First commit<br />
------------------------------------------------------------------------<br />
r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines<br />
Changed paths:<br />
A /trunk<br />
A /trunk/file1<br />
A /trunk/file2<br />
A /trunk/folder1<br />
A /trunk/folder1/somefile<br />
A /trunk/folder2<br />
A /trunk/folder2/somefile<br />
<br />
Initial import into the repository.<br />
</pre><br />
<br />
You can also invoke the log command on a particular file/path and provide a range of revisions.<br />
For instance to see which commits affected file1 between revisions 4 and 6, one could use:<br />
<pre><br />
$ svn log --verbose --revision 4:6 file1<br />
... <- log output<br />
</pre><br />
<br />
==diff==<br />
After you have modified something, it's sometimes nice to see what you've actually done. This is done with the diff command. For instance add some text to file1 and use diff to see what you have done.<br />
<pre><br />
$ svn diff file1<br />
Index: file1<br />
===================================================================<br />
--- file1 (revision 3)<br />
+++ file1 (working copy)<br />
@@ -1 +1,4 @@<br />
-Added this line.<br />
+Added this (removed some text here)<br />
+<br />
+Add a new line here<br />
+<br />
</pre><br />
<br />
==blame==<br />
<br />
<pre><br />
$ svn blame file2<br />
2 jprenaud Added some stuff<br />
3 jprenaud Another line<br />
4 jprenaud A third line.<br />
</pre><br />
<br />
<br />
=Resolving conflicts=<br />
<br />
=Other useful commands=<br />
==move==<br />
Rename<br />
<pre><br />
$ svn mv file2 new_file2<br />
A new_file2<br />
D file2<br />
</pre><br />
==import==<br />
==mkdir==<br />
==export==<br />
==merge==<br />
<br />
=To go further=<br />
Subversion red Book<br />
=Pragmatic Programming=<br />
That's all folks. We hope you have the right basis to be</div>Jprenaud