Scheduled Downtime
On Tuesday 24 October 2023 @ 5pm MT the forums will be in read only mode in preparation for the downtime. On Wednesday 25 October 2023 @ 5am MT, this website will be down for maintenance and expected to return online later in the morning.
Normal Operations
The forums are back online with normal operations. If you notice any issues or errors related to the forums, please reach out to help@ucar.edu

Introduction to Subversion

M

mvr

Member
updated 6/24/13: updated with revised conventions for naming branches and their tags
updated 12/10/07: updated with revised conventions for naming branches and their tags
updated 2/08/07: updated 'working with externals' section with proper naming conventions
updated 7/31/06: added summary of example for branch naming conventions; replaced env var $SVNREPO with $SVN to shorten line lengths
updated 7/24/06: split document into 2 parts, added section on naming conventions for branches and their tags
updated 6/9/06: corrected name of external directories file and instructions for using it
updated 3/21/06: added info on resolving conflicts
updated 2/2/06: corrected some typos in instructions for working with externals
updated 1/24/06: added warning about expanded keywords when porting a branch


The following is meant to be a simple illustration of useful subcommands of the Subversion Command Line Client, svn. This is *not* meant as a substitute for reading the recommended text, which is available on-line here: http://svnbook.red-bean.com. Chapter 3: Guided Tour is particularly useful.

* the following assumes the environment variable $SVN has been set to the repository URL: https://svn-ccsm-models.cgd.ucar.edu



Examples for cam development, but applicable to any component

------------------------------------------------------------------------------------------------------
Typical work cycle:

view contents of repository for cam (may also enter URL/path into web browser)
> svn list $SVN/cam1

view list of cam trunk tags
> svn list $SVN/cam1/trunk_tags

checkout the HEAD of cam's trunk into working copy directory
> svn co $SVN/cam1/trunk cam_trunk_head_wc

much faster cam checkout if no further communication with repository is needed
> svn export $SVN/cam1/trunk cam_trunk_head_export

schedule new file in working copy directory for repository addition
> svn add

schedule working copy file for repository deletion
> svn delete

move working copy file or directory to new location
> svn move

view actual changes to working copy files relative to what was checked out
> svn diff

same as previous, only with user-supplied diff command
> svn diff --diff-cmd /usr/bin/diff -x "-b"

view changes relative to an older tag (don't forget the dot after --new)
svn diff --old $SVN/cam1/trunk_tags/ --new .

view state of working copy files relative to latest in repository
> svn status -u

view revision, URL and other useful information about your working copy files
> svn info

update working copy files to HEAD revision in repository
> svn update

if conflicts arise, you may undo unwanted modifications to working copy files
> svn revert

cleanup of conflicts may also require letting svn know things are resolved
> svn resolved

if project uses ChangeLog file for documentation, update it
> emacs cam_trunk_head_wc/models/atm/cam/doc/ChangeLog

commit changes from working copy directory to HEAD revision with log message
> svn commit -m "appropriate message"

tag new version of cam trunk
> svn copy $SVN/cam1/trunk $SVN/cam1/trunk_tags/

view history of log messages for cam's trunk
> svn log $SVN/cam1/trunk

include the paths changed with each revision
> svn log --verbose $SVN/cam1/trunk


-----------------------------------------------------------------------------------------------------
Working with branches:

determine the naming conventions adopted for the project(s) you'll be working with
** see the section on "Naming conventions for branches and their tags" **

make new cam branch from existing tag
> svn copy $SVN/cam1/trunk_tags/ $SVN/cam1/branches/ -m "appropriate message"

checkout the HEAD of a cam branch into working copy directory
> svn co $SVN/cam1/branches/ some_cam_branch_wc

--make changes as described above for trunk work--

view diffs between two cam trunk tags
> svn diff --old $SVN/cam1/trunk_tags/ --new $SVN/cam1/trunk_tags/

merge changes between trunk tags into working copy of a branch
> cd some_cam_branch_wc
> svn merge $SVN/cam1/trunk_tags/ $SVN/cam1/trunk_tags/

--resolve any conflicts, examine working copy status as described above--

commit changes from working copy directory to HEAD revision with log message
> svn commit -m "appropriate message"

tag new version of cam branch
> svn copy $SVN/cam1/branches/ $SVN/cam1/branch_tags/ -m "appropriate message"


----------------------------------------------------------------------------------------------------
Naming conventions for branches and their tags (adopted by cam and clm):

branches should be named starting with a unique string, descriptive of the branch
> svn copy $SVN/clm2/trunk_tags/clm3_expa_60 $SVN/clm2/branches/hydro -m "creating branch for development of hydro code"

branch tags should go in a subdirectory under under the project's branch_tags directory using the name of the branch and ending in '_tags'
> svn mkdir $SVN/clm2/branch_tags/hydro_tags -m "creating subdirectory for branch tags"

an initial branch tag should be created marking the start point of the branch and a numeric increment should be used in the tag name along with the trunk tag it is up to date with
> svn copy $SVN/clm2/branches/hydro $SVN/clm2/branch_tags/hydro_tags/hydro_n00_clm3_expa_60 -m "making initial branch tag"

subsequent tags reflecting branch work should be incremented accordingly
> svn co $SVN/clm2/branches/hydro hydro_wcopy
> cd hydro_wcopy
** make changes **
> svn commit -m "committing hydro branch work"
> svn copy $SVN/clm2/branches/hydro $SVN/clm2/branch_tags/hydro_tags/hydro_n01_clm3_expa_60 -m "making new branch tag"

updating a branch to newer versions of the trunk should be reflected in the tag names, but the branch name itself remains unchanged
> cd hydro_wcopy
> svn update
> svn commit -m "updating branch to latest version of trunk"
> svn copy $SVN/clm2/branches/hydro $SVN/clm2/branch_tags/hydro_tags/hydro_n01_clm3_expa_65 -m "making branch tag"

branching from branches should be done in a similar manner
example summary...

trunk:
$SVN/clm2/trunk

some trunk tags:
clm3_expa_60
clm3_expa_61
clm3_expa_62

branch:
$SVN/clm2/branches/hydro

some branch tags:
$SVN/clm2/branch_tags/hydro_tags/hydro_n00_clm3_expa_60
$SVN/clm2/branch_tags/hydro_tags/hydro_n01_clm3_expa_60
$SVN/clm2/branch_tags/hydro_tags/hydro_n01_clm3_expa_62
$SVN/clm2/branch_tags/hydro_tags/hydro_n02_clm3_expa_62

branch-of-branch:
$SVN/clm2/branches/hydbob

some branch-of-branch tags:
$SVN/clm2/branch_tags/hydbob_tags/hydbob_n00_hydro_n01_clm3_expa_62
$SVN/clm2/branch_tags/hydbob_tags/hydbob_n01_hydro_n01_clm3_expa_62
$SVN/clm2/branch_tags/hydbob_tags/hydbob_n01_hydro_n02_clm3_expa_62
$SVN/clm2/branch_tags/hydbob_tags/hydbob_n02_hydro_n02_clm3_expa_62


continued on part 2...
 
M

mvr

Member
...continued from part 1

-----------------------------------------------------------------------------------------------------
Working with externals:

checkout the HEAD of cam's trunk into working copy directory
> svn co $SVN/cam1/trunk cam_trunk_head_wc

view the property set for cam's external definitions
> svn propget svn:externals cam_trunk_head_wc

view revision, URL and other useful information specific to external files
> cd cam_trunk_head_wc/models/lnd/clm2/src
> svn info main

create new clm branch for mods required of cam
> svn copy $SVN/clm2/trunk_tags/ $SVN/clm2/branches/ -m "appropriate message"

have external directories in working copy refer to new clm branch to make changes
> svn switch $SVN/clm2/branches//src/main main

--make changes to clm files--

when satisfied with changes and testing, commit to HEAD of clm branch
> svn commit main -m "appropriate message"

tag new version of clm branch - review naming conventions!
> svn copy $SVN/clm2/branches/ $SVN/clm2/branch_tags/_tags/ -m "appropriate message"

have external directories in working copy refer to new clm tag
> svn switch $SVN/clm2/branch_tags/_tags//src/main main

modify cam's property for external definitions in working copy
> emacs cam_trunk_head_wc/SVN_EXTERNAL_DIRECTORIES

--point definition to URL of new-tag-name--

set the property
> svn propset svn:externals -F SVN_EXTERNAL_DIRECTORIES cam_trunk_head_wc

--continue with other cam mods--

commit changes from working copy directory to HEAD of cam trunk - NOTE: a commit from here will *NOT* recurse to external directories
> cd cam_trunk_head_wc
> svn commit -m "appropriate message"

tag new version of cam trunk
> svn copy $SVN/cam1/trunk $SVN/cam1/trunk_tags/ -m "appropriate message"


------------------------------------------------------------------------------------------------------
Porting a branch from CVS to SVN

1 start with a CVS working copy that is the head of your CVS branch - be
careful not to have any expanded CVS keywords in files being ported, as
they will appear as stagnant comments in SVN
2 determine the last CVS trunk tag relevant for the branch or sandbox being
ported - this "migration tag" also exists in SVN

cam1 cam3_2_41
clm2 clm3_expa_48
pop ccsm_pop_1_4_20050826
pop2 ccsm_pop_2_1_20051111
csim4 csim5_2_1
cpl6 cpl6_c051016
csm_share share3_051205
scripts scripts_b051207
bld bld_b051130
datm7 datm7_051205
latm6 latm6_c050810
dlnd6 dlnd6_c051111
docn7 docn7_051205
dice6 dice6_c050810
dead6 dead6_a051006
mph mph_b031010
mct MCT_2_2_0_051207

3 with CVS, update your working copy to the migration tag as you normally would
4 determine the changes unique to your revised working copy, relative to the
migration tag (files added, files removed, and files modified)
5 with SVN, create a working copy that is the head of a newly created
branch, branched from the migration tag - see example for "Working with
branches"
6 add the changes identified in step 4 to your SVN working copy and test -
be careful not to delete Subversion's adminisation files (housed in
subdirectories called .svn and present in each working copy directory)
during this process
7 test, commit and tag
8 merge in desired trunk changes that have evolved within the new repository -
see example for "Working with branches"

at this point, you may have directories in your working copy scheduled for
deletion and replaced with external definitions...to populate your working
copy with the external files (which you'll likely want for testing), you must
first individually commit the directories scheduled for deletion, then run
'svn update'...doing an update prior to the commits will result in an error
with a message similar to this:

Fetching external item into ''
svn: Working copy '' locked
svn: run 'svn cleanup' to remove locks (type 'svn help cleanup' for details)

This approach is recommended over committing your entire working copy
before ample testing has been done.

for example:
> svn status -u
...
D models/csm_share
...

> svn commit models/csm_share -m "committing directory scheduled for deletion and replaced with external"

--repeat for all such directories--

> svn update

9 test, commit and tag
 
M

mvr

Member
...continued from part 1

-----------------------------------------------------------------------------------------------------
Working with externals:

checkout the HEAD of cam's trunk into working copy directory
> svn co $SVN/cam1/trunk cam_trunk_head_wc

view the property set for cam's external definitions
> svn propget svn:externals cam_trunk_head_wc

view revision, URL and other useful information specific to external files
> cd cam_trunk_head_wc/models/lnd/clm2/src
> svn info main

create new clm branch for mods required of cam
> svn copy $SVN/clm2/trunk_tags/ $SVN/clm2/branches/ -m "appropriate message"

have external directories in working copy refer to new clm branch to make changes
> svn switch $SVN/clm2/branches//src/main main

--make changes to clm files--

when satisfied with changes and testing, commit to HEAD of clm branch
> svn commit main -m "appropriate message"

tag new version of clm branch - review naming conventions!
> svn copy $SVN/clm2/branches/ $SVN/clm2/branch_tags/_tags/ -m "appropriate message"

have external directories in working copy refer to new clm tag
> svn switch $SVN/clm2/branch_tags/_tags//src/main main

modify cam's property for external definitions in working copy
> emacs cam_trunk_head_wc/SVN_EXTERNAL_DIRECTORIES

--point definition to URL of new-tag-name--

set the property
> svn propset svn:externals -F SVN_EXTERNAL_DIRECTORIES cam_trunk_head_wc

--continue with other cam mods--

commit changes from working copy directory to HEAD of cam trunk - NOTE: a commit from here will *NOT* recurse to external directories
> cd cam_trunk_head_wc
> svn commit -m "appropriate message"

tag new version of cam trunk
> svn copy $SVN/cam1/trunk $SVN/cam1/trunk_tags/ -m "appropriate message"


------------------------------------------------------------------------------------------------------
Porting a branch from CVS to SVN

1 start with a CVS working copy that is the head of your CVS branch - be
careful not to have any expanded CVS keywords in files being ported, as
they will appear as stagnant comments in SVN
2 determine the last CVS trunk tag relevant for the branch or sandbox being
ported - this "migration tag" also exists in SVN

cam1 cam3_2_41
clm2 clm3_expa_48
pop ccsm_pop_1_4_20050826
pop2 ccsm_pop_2_1_20051111
csim4 csim5_2_1
cpl6 cpl6_c051016
csm_share share3_051205
scripts scripts_b051207
bld bld_b051130
datm7 datm7_051205
latm6 latm6_c050810
dlnd6 dlnd6_c051111
docn7 docn7_051205
dice6 dice6_c050810
dead6 dead6_a051006
mph mph_b031010
mct MCT_2_2_0_051207

3 with CVS, update your working copy to the migration tag as you normally would
4 determine the changes unique to your revised working copy, relative to the
migration tag (files added, files removed, and files modified)
5 with SVN, create a working copy that is the head of a newly created
branch, branched from the migration tag - see example for "Working with
branches"
6 add the changes identified in step 4 to your SVN working copy and test -
be careful not to delete Subversion's adminisation files (housed in
subdirectories called .svn and present in each working copy directory)
during this process
7 test, commit and tag
8 merge in desired trunk changes that have evolved within the new repository -
see example for "Working with branches"

at this point, you may have directories in your working copy scheduled for
deletion and replaced with external definitions...to populate your working
copy with the external files (which you'll likely want for testing), you must
first individually commit the directories scheduled for deletion, then run
'svn update'...doing an update prior to the commits will result in an error
with a message similar to this:

Fetching external item into ''
svn: Working copy '' locked
svn: run 'svn cleanup' to remove locks (type 'svn help cleanup' for details)

This approach is recommended over committing your entire working copy
before ample testing has been done.

for example:
> svn status -u
...
D models/csm_share
...

> svn commit models/csm_share -m "committing directory scheduled for deletion and replaced with external"

--repeat for all such directories--

> svn update

9 test, commit and tag
 
sacks

sacks

Bill Sacks
CSEG and Liaisons
Staff member
Also, see the scripts here: https://svn-ccsm-models.cgd.ucar.edu/tools/svn_scripts/trunk/checked out on yellowstone here: $CESMDATAROOT/tools/svn_scripts This directory contains scripts that are useful for working with branches, such as scripts to assist you with making a new branch or a new branch tag. See the README file in that directory for details.
 
sacks

sacks

Bill Sacks
CSEG and Liaisons
Staff member
Also, see the scripts here: https://svn-ccsm-models.cgd.ucar.edu/tools/svn_scripts/trunk/checked out on yellowstone here: $CESMDATAROOT/tools/svn_scripts This directory contains scripts that are useful for working with branches, such as scripts to assist you with making a new branch or a new branch tag. See the README file in that directory for details.
 
sacks

sacks

Bill Sacks
CSEG and Liaisons
Staff member
See:https://wiki.ucar.edu/display/ccsm/Using+SVN+to+Work+with+CLM+Development+BranchesFor an updated guide on working with svn. This is written specifically for CLM, but is applicable to most other CESM components. This documents both the native svn commands and their alternatives using some wrapper scripts that we have written.
 
sacks

sacks

Bill Sacks
CSEG and Liaisons
Staff member
See:https://wiki.ucar.edu/display/ccsm/Using+SVN+to+Work+with+CLM+Development+BranchesFor an updated guide on working with svn. This is written specifically for CLM, but is applicable to most other CESM components. This documents both the native svn commands and their alternatives using some wrapper scripts that we have written.
 
You must log in or register to reply here.
Top