-- PrzemyslawPaprocki - 02-Nov-2010

g4svn - documentation

g4svn - is a tool for Geant4 developers for ease the use of the Geant4 SVN repository.

1) Architecture

The architecture is shown on the following picture:

You will be using two tools.

• g4svn - described in this manual,
• geant4tags - bonsai replacement, described here https://twiki.cern.ch/twiki/bin/view/Main/G4TagsManual

The Geant4 SVN repository is hosted by CERN SVN Service. There are many SVN servers hosting many projects accessible (for authorized user) under:

svn+ssh://svn.cern.ch/reps/PROJECT_NAME

as Geant4 repository is named geant4, it is available under svn+ssh://svn.cern.ch/reps/geant4.

One of the feature of the SVN repositories are hook programs. These programs are run by SVN repository when certain action happens. They usually invoke other programs (provided by the repository administrator) which can be written in any programming language. Examples of the hooks:

• pre-commit - is being invoked before commit. They usually check if SVN repository should allow user to commit changes,
• post-commit - is being invoked after commit - They can for example send an e-mail with some information about the commit.
• there are many more hooks

Geant4 SVN repository provides pre-commit hook which:

• checks if before tagging, changes were committed to the trunk,
• implements sticky tags - once the tag was created, one should not be able to change it,
• stores information about the tag in the geant4tags web application database.

If pre-commit hook finds any problem, it sends error message to the user and blocks the commit.

On Your machine, You will have some Geant4 working copy and a helper tool g4svn. In general, You will be using native SVN commands but for some tasks (requiring typing longer commands) g4svn can come handy. One of this tasks is tagging. In SVN there is no special functionality implemented for tagging. Tagging is done by copying progress to a special place in the repository. For example, when tagging event category (geant4/source/event), svn command would be (invoked in geant4/source/event):

#Tagging event with the tag name event-VXX-YY-ZZ
svn copy . svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/_symbols/event-VXX-YY-ZZ -m "Creating tag event-VXX-YY-ZZ"

Command copies content of the current directory into tags/geant4/source/event/_symbols/event-VXX-YY-ZZ directory in the Geant4 SVN repository. More information about tagging using Geant4 SVN repository and the repository layout can be found further in this documentation.

In progress of creating a tag, the information about it is being read by pre-commit SVN hook. It stores the tag information in the geant4tags web application database which is located on some machine at CERN.

Another machine serves the geant4tags web application. You can access it under https://sftweb.cern.ch/geant4/geant4tags. Note that You have be to logged in. You can login by clicking the blue "Login" anchor in the top right corner of the web page. Then, a new option "Web Applications" will appear in the main menu. One of the sub-options is "Geant4 Tags".

geant4tags is a bonsai replacement. It lets You browse and change information about the Geant4 tags. In most cases, Your actions will be proposing the tags.

2) General information about Geant4 SVN repository and g4svn

SVN differs from CVS. CVS revisions files, SVN the whole project tree. Every commit creates another revision of the whole project tree. This means that the easiest way to think about SVN is that it is only a file system with additional time line.

Every commit does a snapshot of the current project files system. Of course SVN knows what has happened between commits.

A common pattern, of the startup SVN repository project tree, is to have trunk, tags and branches directory.

Please remember that since SVN revision whole project tree (WHOLE repository!) it also revisions tags or branches if You commit changes in the trunk.

In the trunk directory the main development line takes place (HEAD). In SVN there is no special functionality implemented for tagging or branching. These are done by svn copy current progress into the tags/branches directory i.e tagging whole project:

svn copy svn+ssh://REPOSITORY_URL/project_name/trunk svn+ssh://REPOSITORY_URL/project_name/tags/tag_name -m "Tagging whole project"

Names tags, branches are sometimes called symbols. In this documentation, symbols word will be used from time to time and it means just either branch or tag.

Tags and branches are just some folder in the repository where You copy progress. CVS keeps separate information for every file in the repository. This information contains:

• history - changes between commits, files has it's own revision counter.
• symbols - tags and branches of the file. If You ask CVS about some tag, CVS just searches for the files that have this symbol name in the file properties.

SVN tracks changes for the whole repository, global revision counter. Files also do not have any properties concerning symbols. That's is why tagging is just copying files that You tag into special place in the repository - the tags directory which is just some directory in the repository, nothing more, nothing less. Because tags should not be changed (sticky tags), SVN administrators usualy provide SVN pre-commit hook which can check if developer tries to change tags directory and then blocks this attempt.

In this documentation and usually when speaking about SVN, term tagging really means copy something to the tags directory in the repository.

Because Geant4 developers create tags and branches on different categories of the project (not only top level but also its subdirectories), We had to come up with the solution to the problem of storing symbols. The idea was to have the repository tags/branches directory with the same directory layout as Geant4 project plus _symbols directory at every level where the tags/branches could have been stored:

The CVS repository has been migrated to SVN with this idea and You can browse it under: https://svnweb.cern.ch/cern/wsvn/geant4

If, for example, You want to see what tags were made on the event category (geant4/source/event), You have to click tags >> geant4 >> source >> event >> _symbols (https://svnweb.cern.ch/cern/wsvn/geant4/tags/geant4/source/event/_symbols/) or use the SVN command list:

#On Unix:
svn list svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/_symbols
#On Windows
svn list https://svn.cern.ch/reps/geant4/tags/geant4/source/event/_symbols

As mentioned before. In SVN tagging is copying. If You take once again the event category and at some point You want to make a tag on it, this operation is copying progress from Your working copy event category to the appropriate place in the repository tags directory:

#Tagging event with the tag name event-VXX-YY-ZZ
svn copy . svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/_symbols/event-VXX-YY-ZZ -m "Creating tag event-VXX-YY-ZZ"

Because this operation changes the project tree in the repository, it will create next revision and thus requires a commit message (here: "Creating tag event-VXX-YY-ZZ")

As Geant4 has many nested directories, typing this command is very inconvenient. That is why we decided to create a tool that could help collaborators with some complicated SVN operations.

g4svn is a Python tool which reads svn info from the directory You are working at and uses it to perform some tasks. If You would type following command in the event category:

svn info

you would receive output similar to:

Path: .
URL: svn+ssh://svn.cern.ch/reps/geant4/trunk/geant4/source/event
Repository Root: svn+ssh://svn.cern.ch/reps/geant4
Repository UUID: 34336f62-cc87-11df-b304-c01ee5b7fa03
Revision: 45101
Node Kind: directory
Schedule: normal
Last Changed Author: ppaprock
Last Changed Rev: 45097
Last Changed Date: 2010-10-22 10:32:26 +0200 (Fri, 22 Oct 2010)

g4svn parses this output and enables You to create a tag simply by typing:

g4svn tag event-VXX-YY-ZZ

g4svn will invoke svn copy command like showed few line before with the only difference in commit message which will be "This tag was manufactured by g4svn to create tag event-VXX-YY-ZZ" g4svn gives You some more functionality which is described in this documentation.

Any time You can type

g4svn -h

or

g4svn --help

in the command line once the script has been properly configured to see help message.

2) Requirements

• SVN client version at least 1.4.2. Information about SVN clients for different platforms can be found here: http://subversion.apache.org/packages.html
• Python version at least 2.3.

3) Configuration

a) Getting g4svn

You can either:

checkout it

In the desired directory You can run command

svn co svn+ssh://USERNAME@svn.cern.ch/reps/g4tools/trunk/svntools/g4svn g4svn

to get the most current version of g4svn.

from Geant4 dev area

/afs/cern.ch/sw/geant4/dev/scripts

download it

http://geant4.cern.ch/collaboration/g4svn.zip

b) Setup

For convenient use of the g4svn it is recommended to add directory where the applications is to the PATH environment variable. This will allow You to run g4svn as

g4svn tag tag-name-VXX-YY-ZZ

rather then

/path/to/g4svn/g4svn tag tag-name-VXX-YY-ZZ

Linux/Mac

You need to have python installed (i.e. on SLC5 yum install python) and SVN (i.e. on SLC5 yum install subversion).

For convenient use, it is recommended to add PATH to the directory where the g4svn is:

export PATH=$PATH:/path/to/g4svn

Windows

• Go to Environment Variables window,

This can be found following these steps:

On Windows Vista/7:

1. Click "Start"
2. Right click on "Computer"
3. Choose "Properties"
4. On the left choose "Advanced system settings"
5. Click "Environment Variables"
6. New window will pop up which is the one we've been looking for.

On Windows XP:

1. Right click on "Computer" - If You don't have it on Desktop then You can find in "Start Menu" after clicking "Start"
2. Choose "Properties"
3. Click tab "Advanced"
4. Click "Environment Variables"
5. New window will pop up which is the one we've been looking for.

• Add path to g4svn to the PATH environment variable - separated by ';',

In User variables for ... add or edit PATH environment variable. Insert or append path to the g4svn like such:

g4svn is a Python script and You need to tell Windows that You want to execute Python scripts as programs

• Add .PY; to the environment variable PATHEXT,

In System variables edit PATHEXT environment variable. Append .PY; to the variable as such:

• Go to g4svn directory and change the name of the file g4svn to g4svn.py.

c) SVN repository access

Geant4 SVN repository is hosted by CERN Central SVN Service . You can access it with Your CERN account login and password. There are several methods to access SVN repository. The two recommended by CERN are accessing via svn+ssh protocol and https protocol.

svn+ssh://svn.cern.ch/reps/geant4/

or

https://svn.cern.ch/reps/geant4/

svn+ssh is faster and more secure but it needs some more configuration on Windows. When using svn+ssh, in general SVN will ask You for password per every svn command that connects to the repository. g4svn can run multiple svn commands per operation in order to perform some validation. That is why You could be asked for password several times when using g4svn.

You can bypass this inconvenience by configuring SSH access. When using https, SVN should ask You for the password only once when checkouting the project and the password will be cashed in the SVN administrative area.

We recommend to use

• svn+ssh on Linux/Mac - tutorial how to configure SSH access (to avoid being ask for the password every time) can be found here: http://svn.web.cern.ch/svn/howto.php#accessing-sshlinux
• https on Windows

these are the default options in g4svn. If You decide to use different protocol then it can be changed in the lib/settings.py file under g4svn directory.

4) g4svn options

g4svn has several subcommands described bellow. Any time You can type

g4svn -h

or

g4svn --help

to print out the help.

a) Checkout

This option allows You to checkout the reference tag, branch, or trunk of the Geant4 project.

synopsis

g4svn checkout [OPTIONS] ARG

alternate name: co

g4svn co [OPTIONS] ARG

Possible ARG values

list

 
g4svn checkout --login=USERNAME list

Will print You available tags and branches on geant4 i.e.:

         ---------------- g4svn ---------------- 

Available options:
tags:
BB00-01
BB00-02
Configure-V05-02-00
Configure-V06-01-00
(....more here....)
geant4-09-03-ref-06
geant4-09-03-ref-07
geant4-09-04-beta-01
geant4-09-04-beta-cand-00
geant4-09-04-beta-cand-01
geant4-09-04-beta-cand-02
geant4-09-04-beta-cand-03
(....more here....)
branches:
(....more here....)
geant4-09-02-patches_branch
geant4-09-02-ref-05-branch
geant4-09-03-patches_branch
geant4-09-03-ref-00-branch
(....more here....)

trunk

g4svn gives You possibility to checkout the trunk of the Geant4 project:

g4svn checkout --login=USERNAME trunk

tag name

If You want to checkout a reference tag, i.e geant4-09-03-ref-07 then the command in g4svn would be:

g4svn checkout --login=USERNAME geant4-09-03-ref-07

branch name

If You want to checkout a branch then You have to choose branch name from the list given by command g4svn co list and then:

g4svn checkout --co-branch --login=USERNAME geant4-SOME-BRANCH

Available options

• -l(--login) - CERN login, in general this option is needed when You first interact with Geant4 SVN repository,
• --co-branch, --branch - flag indicating that g4svn should checkout the branch,
• --dir-name - destination directory of the checkout, default: geant4

Examples

Checkout Geant4 trunk to directory geant4

g4svn checkout --login=USERNAME trunk

Checkout Geant4 tag to directory geant4

g4svn checkout --login=USERNAME geant4-09-03-ref-07

Checkout Geant4 branch to directory geant4-branch

g4svn checkout --login=USERNAME --dir-name=geant4-branch --branch geant4-SOME-BRANCH

b) Switch

Every file and directory in Your working category corresponds to some path in the repository. For example if You did checkout the tag geant4-09-03-ref-07 and in /geant4/source/event/ invoked command:

svn info

then the output would be similar to:

Path: .
URL: svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/_symbols/geant4-09-03-ref-07/source/event
Repository Root: svn+ssh://svn.cern.ch/reps/geant4
Repository UUID: 34336f62-cc87-11df-b304-c01ee5b7fa03
Revision: 45150
Node Kind: directory
Schedule: normal
Last Changed Author: asaim
Last Changed Rev: 44844
Last Changed Date: 2010-08-09 18:43:12 +0200 (Mon, 09 Aug 2010)

In the second line You have the information about the URL that this directory points to in the repository. In this example, working copy event category points to corresponding event category that was included within the tag geant4-09-03-ref-07. svn+ssh://svn.cern.ch/reps/geant4 is the root of the Geant4 SVN repository. The next folder is tags. The tag is geant4-09-03-ref-07 (which was a tag on geant4 directory) because this is the name that stands just after symbols. Since geant4-09-03-ref-07 tagged geant4 then just after the tag name stands the event category path - source/event.

The trunk is the place where the main development line takes place. Trunk and branches are the places where You can do changes. Usually, after checking out some Geant4 tag, You will want to switch some category to the trunk, or some branch.

svn switch commands can 'tune' some of your working copy categories. Continuing previous example, if You want to start working on a category, You have to switch Your event category to the trunk:

#notice the . at the end - switching current category to the URL provided as a first parameter
svn switch svn+ssh://svn.cern.ch/reps/geant4/trunk/geant4/source/event . 

g4svn enables You to conveniently use svn swtich command without the need to type long commands.

synopsis

g4svn switch [OPTIONS] ARGS

alternate name: sw

g4svn sw [OPTIONS] ARG

ARGS values

list:

g4svn switch list

This command will print You tags and branches on every category containing Your category. These are candidates for the switch.

trunk

g4svn switch trunk 

This command will switch category You are working on to the trunk (HEAD).

tag name

g4svn switch tag-name-VXX-YY-ZZ 

This command will switch category You are working on to the tag with name tag-name-VXX-YY-ZZ.

branch name

g4svn switch --sw-branch branch-name-VXX-YY-ZZ 

This command will switch category You are working on to the branch with name branch-name-VXX-YY-ZZ.

files/directories

You can also select files/directories You want to switch:

g4svn switch tag-name-VXX-YY-ZZ History src/ 

This command will only switch History and src/ to tag tag-name-VXX-YY-ZZ.

Available options

• --sw-branch, --branch - flag indicating that g4svn should switch on to the branch,

Examples:

Switch current category to the trunk:

g4svn switch trunk

(Supposing that You are at /geant4/source/event/ ) Switch event category to tag event-VXX-YY-ZZ:

g4svn switch event-VXX-YY-ZZ

(Supposing that You are at /geant4/source/event/ ) Switch event category to branch event-branch

g4svn switch --branch event-branch

c) Tag

g4svn enables You conveniently create a tag on the working category.

synopsis

g4svn tag [OPTIONS] ARGS

ARG values

As a ARG value, You should at least provide the name of the tag. If You would only type:

g4svn tag tag-name-VXX-YY-ZZ

then g4svn will tag whole contents of the category You are working on - it will copy everything from Your category to appropriate directory in the repository.

You also have option to do a selective tag:

g4svn tag tag-name-VXX-YY-ZZ file1, file2, dir1, dir2 ....

Available options

• -p(--proposed) - propose a tag on the geant4tags web application,
• -d(--description) - if tag is being proposed (via -p option), then this option is required and means description for a tag,
• -b(--bugfix) - optional flag to go with option -p. Indicates that tag does a bugfix,
• --bugfix-number - optional flag to go with option -p. Indicates that tag resolves bugzzila problem number.

Examples

Simply create a tag,

g4svn tag tag-name-VXX-YY-ZZ

This command will create a tag on a category that You are working on. Tag will be stored in the repository under appropriate path and tag information entry will occur at the geant4tags web application.

Creating a tag with immediate proposing at the geant4tags web application

g4svn provides -p ( --proposed ) option. It tells g4svn that the tag, that's being created, should be immediately proposed at the geant4tags web application. When using this option it is also required to specify description for the tag using -d ( --description ) option. Proposed tag can have bugifx. For that, g4svn provides options -b ( --bugfix ) and ( --bugfix-number ). Please consider the following examples:

Tag proposed without bugfix

g4svn tag -p -d "Tag without bugfix" tag-name-VXX-YY-ZZ 

Tag proposed with bugfix

g4svn tag -p -b -d "Tag with bugfix" tag-name-VXX-YY-ZZ 

Tag proposed with bugzilla problem number

g4svn tag -p --bugfix-number=666 -d "Tag fixing problem 666 on bugzilla" tag-name-VXX-YY-ZZ 

Selective tagging

Exclude entries manually

Sometimes You don't want to tag the whole category content. Let's take once again event category. After You would switch to this category to the trunk You would have received the following content in this directory:

geant4/
- source/
--- event/
----- include/
----- src/
----- test/
----- GNUMakefile
----- History

Suppose, You don't want to include the test directory in the tag. You should svn remove this directory before making a tag:

bash-3.2$ svn update
At revision 42695.
bash-3.2$ 
bash-3.2$ svn rm test
D         test/GeneralParticleSource/test15.g4mac
D         test/GeneralParticleSource/test16.g4mac
D         test/GeneralParticleSource/test17.g4mac
(....more here....)
D         test/GeneralParticleSource/test14.g4mac
D         test/GeneralParticleSource
D         test
bash-3.2$ 

It is recommended to run svn update before removing anything to synchronize with the repository.

Because g4svn creates a tag by copying from Your working path, the tag will not include entries that You svn removed.

Then You can tag the category:

g4svn tag event-VXX-YY-ZZ

REMEMBER

Files and directories that You have removed in the first step are still scheduled to be removed from the repository after commit. In general You will like to have them back. For that, You can run svn revert with -R option:

svn revert . -R

WARNING

Before crating a tag, g4svn checks if there are any uncommitted files or directories. It only does exceptions for entries that have been marked as being deleted - so to allow selective tagging. You have to distinguish what do You want to delete entirely and what You just don't want to include in the tag. If You want to delete something from the directory, use svn remove and then svn commit to accept changes. If You don't want to include something in the tag then svn remove it, create a tag and then svn revert . -R Your working directory or use selective tagging implemented in g4svn descried in the next point.

Selective tagging using g4svn

Steps shown in the previous point can be automatized. Selective tagging has been also implemented in g4svn. You can give the list of the files or directories when You do the tag.

g4svn tag event-VXX-YY-ZZ include/ src/ GNUMakefile History

This command has the same effect as the example shown in the previous point.

d) Branch

This option is for advanced users. This subcommand allows You to create a branch. The only thing it does, is coping current working copy category content to appropriate path in Geant4 SVN repository branches directory.

This command does not automatically switch Your category to the branch. If You want to create and then use Your branch the sequence to do that with g4svn would be:

#Create new branch
g4svn branch branch-name
#Switch to that branch
g4svn sw --branch branch-name

synopsis

g4svn branch ARG

ARG values

ARG value is the name of the branch

g4svn branch branch-name

Available options

g4svn branch does not take any specific options.

Examples

Create a branch:

g4svn branch branch-name

e) Merge

This option is for advanced users. It allows to merge changes either from tag, other branch or trunk to Your branch, or from Your branch to the trunk or other branch. To be compatible with svn client 1.4.2, this command always compares two corresponding directory tree and applies differences to Your working copy. Please see http://svnbook.red-bean.com/en/1.4/svn.branchmerge.html to find out how You can branch in SVN and to understand what g4svn is trying to do.

Supposing You are working on a branch of the Geant4 project -called 'GEANT4-BRANCH' - and particularly You do changes in the event category ( geant4/source/event ). You would like to merge Your History file and src/ directory with the one that is in tag event-VXX-YY-ZZ. g4svn command to do this would be:

g4svn merge event-VXX-YY-ZZ History src/

This will be translated to SVN commands:

svn merge svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/_symbols/GEANT4-BRANCH/source/event/src/ svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/_symbols/event-VXX-YY-ZZ/src/ . 
svn merge svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/_symbols/GEANT4-BRANCH/source/event/History svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/_symbols/event-VXX-YY-ZZ/History .

Please note that g4svn compares paths from the repository and applies the result to Your working copy category ( . - at the end).

Later on, You can merge back Your changes from branch to - for example - trunk. You just need to be switched to the trunk and then:

g4svn merge --me-branch GEANT4-BRANCH History src/

You don't have to specify list of files and directories. The following command also works:

g4svn merge event-VXX-YY-ZZ

This time, the whole category content will be merged.

synopsis

g4svn merge [OPTIONS] ARGS

ARGS values

trunk

Merges corresponding trunk path to Your working copy category

g4svn merge trunk

tag name

Merges corresponding tag path to Your working copy category

g4svn merge tag-name-VXX-YY-ZZ

branch name

Merges corresponding branch path to Your working copy category

g4svn merge --me-branch branch-name

file/directories names after symbol name

You can provide files/directories to be copied after the symbol name (example for trunk):

g4svn merge trunk file1 dir1 file2 ...

Available options

• --me-branch, --branch - flag indicating that g4svn should merge with branch identified by given name.

Examples

Merge with trunk

g4svn merge trunk

Merge with tag tag-name-VXX-YY-ZZ

g4svn merge tag-name-VXX-YY-ZZ

Merge with branch branch-name

g4svn merge --branch branch-name

f) Copy

This option is for advanced users. It allows to copy file from corresponding path from tags, branches and trunk to Your working copy. Suppose You are working on branch geant4-branch, particularly on the event category ( geant4/source/event ) and You would like to copy a file that exists in tag event-VXX-YY-ZZ but not in Your working copy. g4svn command for this operation would be:

g4svn copy event-VXX-YY-ZZ file_to_copy

This will be translated to SVN command:

svn copy svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/_symbols/event-VXX-YY-ZZ/file_to_copy .

Another situation when this command can be useful is when You would like to revive a file or directory from the past. For example You are working on the trunk and You accidentally removed file README. This operation created revision X. You know that in revision Y=X-1 this file existed. You can revive it using command:

g4svn copy -r Y trunk README

synopsis

g4svn copy [OPTIONS] ARGS

alternate name: cp:

g4svn cp [OPTIONS] ARG

ARGS values

trunk

Copy from the corresponding trunk path to Your working copy

g4svn copy trunk

tag name

Copy from the corresponding tag path to Your working copy

g4svn merge tag-name-VXX-YY-ZZ

branch name

Copy from the corresponding branch path to Your working copy

g4svn copy  --cp-branch branch-name

file/directories names after symbol name

You can provide files/directories to be copied after the symbol name (example for trunk):

g4svn copy trunk file1 dir1 file2 ...

Available options

• --cp-branch, --branch - flag indicating that g4svn should copy from branch identified by given name,
• -r (--revision) - flag indicating that g4svn should copy from revision with given number.

Examples

Copy file1 from the revision 1000 of the trunk

g4svn copy -r 1000 trunk file1

Copy everything from the tag tag-name-VXX-YY-ZZ

g4svn copy tag-name-VXX-YY-ZZ

Copy everything from the branch branch-name from revision 2000

g4svn copy --branch --revision=2000 branch-name

5) Working on a category

checkout

The first step is to checkout some Geant4 version. In this example You will be working on the reference tag geant4-09-03-ref-07.

g4svn checkout --login=USERNAME geant4-09-03-ref-07

This command will checkout the reference tag geant4-09-03-ref-07 to the geant4 directory.

switch

You checkouted a reference tag geant4-09-03-ref-07 using g4svn checkout --login=USERNAME geant4-09-03-ref-07 command and now You want to work on the category event (geant4/source/event). If You go to that category (cd geant4/source/event) and invoke command svn info then You will see similar output to:

Path: .
URL: svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/_symbols/geant4-09-03-ref-07/source/event
Repository Root: svn+ssh://svn.cern.ch/reps/geant4
Repository UUID: 34336f62-cc87-11df-b304-c01ee5b7fa03
Revision: 45101
Node Kind: directory
Schedule: normal
Last Changed Author: asaim
Last Changed Rev: 44844
Last Changed Date: 2010-08-09 18:43:12 +0200 (Mon, 09 Aug 2010)

In the second line:

URL: svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/_symbols/geant4-09-03-ref-07/source/event

You have the information about SVN repository URL on witch You are currently working.

You are at source/event in the reference tag geant4-09-03-ref-07. You cannot do changes here because it is a tag. At first You have to switch the category to the trunk:

g4svn switch trunk

Output will be something like:

         ---------------- g4svn ---------------- 

Reading SVN information about directory:
Repository root: svn+ssh://svn.cern.ch/reps/geant4
Repository url: svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/_symbols/geant4-09-03-ref-07/source/event
Top level directory: tags
Symbol name: geant4-09-03-ref-07
Project path: geant4/source/event

Switching (Please wait):
A    THIS_FILE_WAS_NOT_IN_TAG
D    THIS_WAS_IN_TAG_BUT_NOT_IN_THE_TRUNK
U    THIS_FILE_HAS_BEEN_UPDATED
C    THIS_FILE_IS_IN_CONFLICT_AFTER_SWITCH
G    THIS_FILE_HAS_BEEN_MERGED
Updated to revision 45150.

now if You type once again:

svn info 

then in URL line You can now see that You are working on the trunk:

URL: svn+ssh://svn.cern.ch/reps/geant4/trunk/geant4/source/event

tag

You checkouted some reference tag i.e. geant4-09-03-ref-07 and then switched the event (geant4/source/event) category to the trunk. Now You are ready to work on that category. In general You will follow the cycle:

1. < < make some changes > >
2. svn status (-u)
3. [GO TO POINT 1 OR 4]
4. svn update
5. svn commit -m "Commit message"
6. [GO TO POINT 1 OR 7]
7. svn update
8. g4svn tag tag-name-VXX-YY-ZZ

1 - making changes,

At first You do some changes to the files and directories. Remember that there are two kinds of changes. Changes to files and changes to the project tree. For those first ,You don't have to inform SVN about anything. SVN will figure out that You have changed files. However, You should tell SVN about changes in the project tree ( files or directories) like:

• adding - svn add
• deleting - svn delete
• moving - svn move
• copying - svn copy
• renaming - svn rename

2 - svn status,

svn status enables You to find out what files or directories have been changed. With option -u it compares Your working copy with the files in the repository (it connects to the repository). Without this option it compares with what You have lastly committed or gained from the repository after invoking svn update - it doesn't connect to the repository

3 - Continue working (go to point 1) or decide to commit changes (go to point 4),

4 - svn update,

Before You can commit, You should check if anybody else haven't changed the same files. If there will be some conflict then SVN will try to merge files. If it will not succeed then You will have to resolve conflicts by Your own. More info: http://svnbook.red-bean.com/en/1.4/svn.tour.cycle.html#svn.tour.cycle.resolve

5 - svn commit,

This command will commit changes to the repository. It requires commit message with the option -m.

6 - Continue working (go to point 1) or decide to tag progress (go to point 7),

7 - svn update

It's really recommended that You once again run svn update before creating a tag. Sometimes directories or files under the category that You are trying to tag have younger revision number - even if svn _status gives You no output (because in fact the directory contents is the same as at the repository but the revision number of Your category is older then the one in the repository). This will prevent Geant4 SVN repository hook to reject Your tag, if everything seems to be ok.

IN GENERAL

If You have problems with tagging but You think You shouldn't have - run svn update,

8 - g4svn tag

In SVN tagging is copying. When You decide to tag Your progress, g4svn will help You with that and construct proper svn copy command.

g4svn tag -p -d "Tagging event" event-VXX-YY-ZZ 

6) CVS vs SVN&g4svn

workflow

CVS:

1: cvs co geant4-09-03-ref-07
2: cd /geant4/source/geometry/magneticfield
3: cvs update
4 <<make some changes here>>
5: cvs commit
6: cvs tag magneticfield-VXX-YY-ZZ

SVN & g4svn:

1: g4svn checkout --login=USERNAME geant4-09-03-ref-07
2: cd /geant4/source/geometry/magneticfield
3: g4svn switch trunk
4: <<make some changes here>>
5: svn commit
6a: g4svn tag magneticfield-VXX-YY-ZZ //If You just want to create a tag and then propose it through the geant4tags web application - a bonsai replacement
6b: g4svn tag -p -b -d "Fixed bug" magneticfield-VXX-YY-ZZ //[Example] If You want to propose a tag which fixes a bug description "Fixed bug"

comparison

CVS	SVN
Check out the current HEAD of the repository
cvs checkout geant4	g4svn co --login=USERNAME trunk
To update the local geant4/ tree and checkout from the repository all last modifications and new files. Being in geant4:
cvs update –d –P	svn update
To see what is changed from the current HEAD version in the repository and the local tree geant4/. Being in geant4
cvs –n update –A	svn status -u
To update just a category in the local geant4/ tree, to a specified tag for it (example, tag "run-V09-01-00" for the run category). Being in geant4/source/run
cvs update -r run-V09-01-00	g4svn switch run-V09-01-00
To update a category to HEAD (therefore removing sticky tags for that category), checking-out possible new files (-d option) and pruning (-P option) empty directories. Example for run category, being in geant4/source/run
cvs update -A -d -P	g4svn switch trunk
To checkout a released tree (e.g. tag "geant4-09-03-ref-07")
cvs checkout -r geant4-09-03 -d geant4	g4svn checkout --login=USERNAME geant4-09-03-ref-07
To update to a specific reference tag (e.g. tag "geant4-09-03-ref-07"). Being in geant4
cvs update -r geant4-09-03-ref-07 -d –P	g4svn switch geant4-09-03-ref-07

7) Details

For every subcommand, g4svn provide option -v(--verbose). With this option, g4svn will print every svn command that it invokes. Printed in console commands do not have chars ' and ". For example if g4svn ivokes command:

svn copy . svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/_symbols/event-VXX-YY-ZZ -m "This message was manufactured by g4svn to create tag event-VXX-YY-ZZ"

then in console You would see:

svn copy . svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/_symbols/event-VXX-YY-ZZ -m This message was manufactured by g4svn to create tag event-VXX-YY-ZZ

Appropriate warning, at the beginning of the program execution is shown, when You run g4svn with -v option:

         ---------------- g4svn ---------------- 

                  [ #### WARNING #####]
In DEBUG mode, printed commands do not contain chars " or ' i.e. for the -m option in svn copy.

Please also note that in the following listings I will be using marks @@ X @@ to indicate what I am currently explaining. These marks are not printed by g4svn!

In this section You can closely look on what does g4svn do.

checkout

g4svn checkout -v --dir-name=g4 --login=USERNAME geant4-09-03-ref-07

Output:

         ---------------- g4svn ---------------- 

                  [ #### WARNING #####]
In DEBUG mode, printed commands do not contain chars " or ' i.e. for the -m option in svn copy.

Checking out (Please wait):

 [DEBUG] Invoking command:
svn checkout svn+ssh://USERNAME@svn.cern.ch/reps/geant4/tags/geant4/_symbols/geant4-09-03-ref-07/ g4 
A    g4/source
A    g4/source/event
A    g4/source/event/test
A    g4/source/event/test/GeneralParticleSource
A    g4/source/event/test/GeneralParticleSource/test15.g4mac
A    g4/source/event/test/GeneralParticleSource/test16.g4mac
....

Nothing particularly interesting here. g4svn just bulids appropriate svn checkout command.

switch

Suppose that You are working on the event category (geant4/source/event) at the trunk:

g4svn switch -v geant4-09-03-ref-07

Output:

         ---------------- g4svn ---------------- 

                  [ #### WARNING #####]
In DEBUG mode, printed commands do not contain chars " or ' i.e. for the -m option in svn copy.

@@ 1 @@
Reading SVN information about directory:
 [DEBUG] Invoking command:
svn info --non-interactive 

Repository root: svn+ssh://svn.cern.ch/reps/geant4
Repository url: svn+ssh://svn.cern.ch/reps/geant4/trunk/geant4/source/event
Top level directory: trunk
Project path: geant4/source/event

@@ 2 @@
Getting list of tags containing geant4/source/event category...
 [DEBUG] Invoking command:
svn list --non-interactive svn+ssh://svn.cern.ch/reps/geant4/tags//geant4/_symbols 

 [DEBUG] Invoking command:
svn list --non-interactive svn+ssh://svn.cern.ch/reps/geant4/tags//geant4/source/_symbols 

 [DEBUG] Invoking command:
svn list --non-interactive svn+ssh://svn.cern.ch/reps/geant4/tags//geant4/source/event/_symbols 

@@ 3 @@
Switching (Please wait):

 [DEBUG] Invoking command:
svn switch --non-interactive svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/_symbols/geant4-09-03-ref-07/source/event . 
D    THIS_FILE_IS_NOT_IN_THE_TAG
Updated to revision 45150.

At first (@@ 1 @@) g4svn examines the category that You are working on. It invokes command svn info and parses the output to get information about:

• Repository root - where is the Geant4 repository and how is it named,
• Category repository URL - where is the working copy category located in repository,
• Symbol type - can be trunk, branches, tags ,
• Project path - what is the project path of the working copy category.

In point @@ 2 @@ g4svn recursively gets information about the tags that can contain working copy category. In this example, event category can be included in tags on paths:

• geant4,
• geant4/source,
• geant4/source/event.

After this point, g4svn knows on what path was the chosen tag. In this example, tag geant4-09-03-ref-07 is on path gean4.

Appropriatly compering project category path and chosen tag path, g4svn is able to bulid svn switch command in point @@ 3 @@.

Please note, that in this example g4svn switches to event category under the tag geant4-09-03-ref-07

svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/_symbols/geant4-09-03-ref-07/source/event

tag

Suppose that You are working on the event category (geant4/source/event) at the trunk and then You create new subdirectory sub-event:

geant4/
- source/
--- event/
----- sub-event/
------- include/
------- src/
------- tests/
------- GNUMakefile
------- History

You did some development in this new directory and now You want to tag it without tests directory (remember to commit this directory first to the repository):

g4svn tag -v --bugfix-number=777 -p -d "Tag proposed, fixing problem nr.777" sub-event-VXX-YY-ZZ GNUmakefile History include/ src/

Output:

         ---------------- g4svn ---------------- 

                  [ #### WARNING #####]
In DEBUG mode, printed commands do not contain chars " or ' i.e. for the -m option in svn copy.

@@ 1 @@
Reading SVN information about the directory:
 [DEBUG] Invoking command:
svn info --non-interactive 

Repository root: svn+ssh://svn.cern.ch/reps/geant4
Category repository URL: svn+ssh://svn.cern.ch/reps/geant4/trunk/geant4/source/event/sub-event
Symbol type: trunk
Project path: geant4/source/event/sub-event

@@ 2 @@
Checking if changes were committed...
 [DEBUG] Invoking command:
svn status -u 

Creating tag sub-event-VXX-YY-ZZ...

@@ 3 @@
Checking category SVN properties...
Setting bugifix property...

 [DEBUG] Invoking command:
svn propset bugfix 777 . 
property 'bugfix' set on '.'

Setting proposed property...

 [DEBUG] Invoking command:
svn propset proposed yes . 
property 'proposed' set on '.'

Commiting properties set...

 [DEBUG] Invoking command:
svn commit --non-interactive -m Setting properties before creating tag sub-event-VXX-YY-ZZ 

@@ 4 @@
Checking if there is a need to add directories to the tags repository tree...
 [DEBUG] Invoking command:
svn list --non-interactive svn+ssh://svn.cern.ch/reps/geant4/ 

 [DEBUG] Invoking command:
svn list --non-interactive svn+ssh://svn.cern.ch/reps/geant4//tags 

 [DEBUG] Invoking command:
svn list --non-interactive svn+ssh://svn.cern.ch/reps/geant4//tags/geant4 

 [DEBUG] Invoking command:
svn list --non-interactive svn+ssh://svn.cern.ch/reps/geant4//tags/geant4/source 

 [DEBUG] Invoking command:
svn list --non-interactive svn+ssh://svn.cern.ch/reps/geant4//tags/geant4/source/event 

@@ 5 @@
Adding path to the repository: svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/sub-event
 [DEBUG] Invoking command:
svn mkdir svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/sub-event --non-interactive -m This message was manufactured by g4svn to add necessary path svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/sub-event. 

Adding path to the repository: svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/sub-event/_symbols
 [DEBUG] Invoking command:
svn mkdir svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/sub-event/_symbols --non-interactive -m This message was manufactured by g4svn to add necessary path svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/sub-event/_symbols. 

@@ 6 @@
Checking if the tag with the name sub-event-VXX-YY-ZZ already exists...
 [DEBUG] Invoking command:
svn list --non-interactive svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/sub-event/_symbols 

@@ 7 @@
Temporary removing tests
 [DEBUG] Invoking command:
svn remove tests 

@@ 8 @@
Copying to svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/sub-event/_symbols/sub-event-VXX-YY-ZZ directory...
Command: svn copy --non-interactive . svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/sub-event/_symbols/sub-event-VXX-YY-ZZ -m "Tag proposed, fixning problem nr.777"

 [DEBUG] Invoking command:
svn copy --non-interactive . svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/sub-event/_symbols/sub-event-VXX-YY-ZZ -m Tag proposed, fixning problem nr.777 

Committed revision 46234.

@@ 9 @@
Reverting temporarily removed files...
 [DEBUG] Invoking command:
svn revert . -R 

Tag created.

At first (@@ 1 @@) g4svn reads the information about the working copy category. In point @@ 2 @@ it checks if changes have been committed to the trunk. This is checked twice, by g4svn and the pre-commit hook. We want to have tags always synchronized with the trunk.

In our example tag is being immediately proposed on the geant4tags web application. At @@ 3 @@ g4svn sets the following svn properties (http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html):

• proposed
• bugfix

and commits them. On the SVN repository side, pre-commit hook (after the tag will have been created) will read those properties and insert tag information to the geant4tags database with Your additional information about bugfix and description (this is taken from the svn copy log message).

At @@ 4 @@ g4svn checks if the path, where the tag should be, exists in the repository. This example shows some rare case when the tag is being created on the directory which wasn't tagged before. Because sub-event is a new directory being tagged, g4svn has to add some necessary paths is the tags repository file system tree (@@ 5 @@).

At @@ 6 @@ g4svn checks if tag with the name sub-event-VXX-YY-ZZ already exists.

This example shows selective tagging. GNUmakefile, History, include/ and src/ where selected for the tag. This means that directory tests should be removed before tagging. At @@ 7 @@ g4svn temporarily svn removes the tests directory.

At @@ 8 @@ g4svn actually creates the tag. It copies appropriately configured current working copy category to corresponding path in tags directory in the Geant4 SVN repository.

Last step (@@ 9 @@) - which occurs only when tagging was selective - is to revert temporarily removed files to restore directory to the state before tagging.

branch

Suppose that You are working on the event category (geant4/source/event) at the trunk:

g4svn branch event-branch

Output:

         ---------------- g4svn ---------------- 

                  [ #### WARNING #####]
In DEBUG mode, printed commands do not contain chars " or ' i.e. for the -m option in svn copy.
@@ 1 @@
Reading SVN information about the directory:
 [DEBUG] Invoking command:
svn info --non-interactive 

Repository root: svn+ssh://svn.cern.ch/reps/geant4
Category repository URL: svn+ssh://svn.cern.ch/reps/geant4/trunk/geant4/source/event
Symbol type: trunk
Project path: geant4/source/event

@@ 2 @@
 [DEBUG] Invoking command:
svn list --non-interactive svn+ssh://svn.cern.ch/reps/geant4/

 [DEBUG] Invoking command:
svn list --non-interactive svn+ssh://svn.cern.ch/reps/geant4//branches 

 [DEBUG] Invoking command:
svn list --non-interactive fsvn+ssh://svn.cern.ch/reps/geant4//branches/geant4 

 [DEBUG] Invoking command:
svn list --non-interactive svn+ssh://svn.cern.ch/reps/geant4//branches/geant4/source 

@@ 3 @@
Adding path to the repository: svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/source/event
 [DEBUG] Invoking command:
svn mkdir svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/source/event --non-interactive -m This message was manufactured by g4svn to add necessary path svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/source/event. 

Adding path to the repository: svn+ssh://svn.cern.ch/reps/geant4/geant4/source/event/_symbols
 [DEBUG] Invoking command:
svn mkdir svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/source/event/_symbols --non-interactive -m This message was manufactured by g4svn to add necessary path svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/source/event/_symbols. 

@@ 4 @@
Command: svn copy --non-interactive . svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/source/event/_symbols/event-branch -m "This message was manufactured by g4svn to create branch event-branch"

 [DEBUG] Invoking command:
svn copy --non-interactive . svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/source/event/_symbols/event-branch -m This message was manufactured by g4svn to create branch event-branch 

Committed revision 42839.

At @@ 1 @@ g4svn reads working copy category information. Then at points @@ 2 @@ and @@ 3 @@ prepares a place in the branches directory in the repository for the new branch (if its required). The last step (@@ 4 @@), is creating the branch by copying current working copy category content to the corresponding path under the branches.

merge

Suppose that You are working on the event category (geant4/source/event) at the branch event-branch:

g4svn merge -v event-tag History src/G4Event.cc

Output:

         ---------------- g4svn ---------------- 

                  [ #### WARNING #####]
In DEBUG mode, printed commands do not contain chars " or ' i.e. for the -m option in svn copy.

@@ 1 @@
Reading SVN information about the directory:
 [DEBUG] Invoking command:
svn info --non-interactive 

Repository root: svn+ssh://svn.cern.ch/reps/geant4
Category repository URL: svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/source/event/_symbols/event-branch
Symbol type: branches
Symbol name: event-branch
Project path: geant4/source/event

@@ 2 @@
Getting list of tags containing geant4/source/event category...
 [DEBUG] Invoking command:
svn list --non-interactive svn+ssh://svn.cern.ch/reps/geant4/tags//geant4/_symbols 

 [DEBUG] Invoking command:
svn list --non-interactive svn+ssh://svn.cern.ch/reps/geant4/tags//geant4/source/_symbols 

 [DEBUG] Invoking command:
svn list --non-interactive svn+ssh://svn.cern.ch/reps/geant4/tags//geant4/source/event/_symbols 

@@ 3 @@
Merging History...
Command: svn merge --non-interactive svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/source/event/_symbols/event-branch/History svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/_symbols/event-tag/History History 

 [DEBUG] Invoking command:
svn merge --non-interactive svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/source/event/_symbols/event-branch/History svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/_symbols/event-tag/History History 
U    History

Merging src/G4Event.cc...
Command: svn merge --non-interactive svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/source/event/_symbols/event-branch/src/G4Event.cc svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/_symbols/event-tag/src/G4Event.cc src/G4Event.cc 

 [DEBUG] Invoking command:
svn merge --non-interactive svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/source/event/_symbols/event-branch/src/G4Event.cc svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/_symbols/event-tag/src/G4Event.cc src/G4Event.cc 
U    src/G4Event.cc

At @@ 1 @@ g4svn reads working copy category information. Then at point @@ 2 @@ it searches for the chosen tag to get information about the path tag it tagged. In the last step (@@ 3 @@), g4svn invokes svn merge commands for chosen files/directories.

copy

Suppose that You are working on the event category (geant4/source/event) at the trunk. You want to change Your version of History with the one that was in revision 40000:

svn rm History
g4svn copy -v -r 40000 trunk History

Output:

         ---------------- g4svn ---------------- 

                  [ #### WARNING #####]
In DEBUG mode, printed commands do not contain chars " or ' i.e. for the -m option in svn copy.
@@ 1 @@
Reading SVN information about the directory:
 [DEBUG] Invoking command:
svn info --non-interactive 

Repository root: svn+ssh://svn.cern.ch/reps/geant4
Category repository URL: svn+ssh://svn.cern.ch/reps/geant4/trunk/geant4/source/event
Symbol type: trunk
Project path: geant4/source/event

@@ 2 @@
Copying History...
Command: svn copy --non-interactivesvn+ssh://svn.cern.ch/reps/geant4/trunk/geant4/source/event/History . 

 [DEBUG] Invoking command:
svn copy --non-interactive svn+ssh://svn.cern.ch/reps/geant4/trunk/geant4/source/event/History . --revision=40000 
A         History

At first (@@ 1 @@) g4svn read information about working copy category. Then it constructs appropriate path and performs copying (@@ 2 @@).

8) Known problems:

• Directory '/some/dir/is/out/of/date' is out of date

Run

svn update

to bring the working directory to the most fresh version.

Please note here that after svn update You could receive svn status output something like:

bash-3.2$ svn status
 M     .

the 'M' is in the second row of the output. This means that the svn properties (http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html) of the directory have been changed. If You haven't changed any svn properties of the directory then there were most likely changed by g4svn (see details of the g4svn tag subcommand). You can revert those changes (svn revert . -R) or commit them. g4svn will automatically discover svn properties of directory next time when You will do a tag and change them if it will be required. * Pre-commit hook does not allow me to crate a tag even if svn status -u does not show any uncommitted changes: Run

svn update

to bring the working directory to the most fresh version.

When You are working on subdirectories of Your category and commit them, they have youngest revision number then Your category. After that, the pre-commit hook has some problem in distinguishing what changes are included in the tag. Running svn update in Your category will synchronize it with the most recent revision in the repository. You should have no more problem with creating a tag after svn update.