This is obsolete

SVN will be retired. This is the old documentation. Refer this page instead.

Using SVN (Subversion) public LHCb Document repository lhcbdocs

LHCbDocs repository has following goals:

• To host document development projects, especially collaborative in nature. Private LHCb-related projects are accepted as well.

• Provide space for sharing of source codes for officially released documents (Notes, Papers) even if developed outside of the repository.

• Space for template development and sharing.

It supplements, not replaces CDS (CERN Document Server). It is open to all LHCb collaborators.

There is more information to be found in the presentation at Oct.26,2010 Tuesday meeting., which may be especially useful to novice SVN users.

Table of Contents

Relation to SVN LHCb code repository

SVN is also used to maintain LHCb software code in a separate repository (lhcb).

There is a lot of useful information about use of SVN for code development in LHCb at this page. Much of it is also relevant for use of lhcbdocs.

The main differences is that while we usually check out projects from lhcb code repository via getpack interface, you will be using "svn co" directly in lhcbdocs. A half-way replacement for getpack functionality exits - see getDoc.py and related tagDoc.py.

Access to lhcbdocs repository

Every member of lhcb-general e-group mailing list has read and write access to lhcbdocs repository. You don't need to sign-up to get write access to it (unlike write access to lhcb software repository which requires membership in lhcb-svn-writers e-group which is not automatic). Other users have no access at all. Once you leave the collaboration you will lose access to it (export your docs before you leave).

Occasionally the SVN server is overloaded - just try svn command again if it fails unexpectedly.

If you are a newcomer to svn, or if you are accessing lhcbdocs remotely you may need to set up your user account and connection to the server.

Please consult LHCb instructions

or more general

CERN IT pages for the instructions.

To see if you can access repository from your unix system try to list the main directory structure of the repository via:

svn ls https://svn.cern.ch/reps/lhcbdocs

This will prompt you for the password. If your userid on the local machine is different than at CERN, just enter anything, then the system will ask you for your username (and then password again). You will not have to enter the password again for subsequent svn commands.

A faster access is provided via ssh:

 

svn ls svn+ssh://svn.cern.ch/reps/lhcbdocs

In this method you can avoid entering password altogether if you follow the procedure outlined at CERN svn pages.

Since it is tedious to type the repository address all the time I recommend defining an environmental variable as a shorthand e.g. (csh):

setenv DLHCB svn+ssh://svn.cern.ch/reps/lhcbdocs

or if using https transport

setenv DLHCB https://svn.cern.ch/reps/lhcbdocs

I use this convention below.

Web browser access to lhcbdocs repository

You can access the repository (read only) with a web browser from any location using either svnweb, or if your prefer Trac. You will be prompted to login with your CERN userid.

This site also offers revision log for each file and ability to download files or entire directories (in .tar.gz format).

You can access specific files in the repository (no browsing however) e.g. via https://svnweb.cern.ch/cern/wsvn/lhcbdocs/Publications/PAPER/2011/044/drafts/v5.4/latex/main.pdf.

This is recommended way if you need to set a link e.g. in your analysis TWiki page.

Please be advised that CERN is no longer supporting lhcbdocs access via "Trac".

lhcbdocs policies

Since everybody in LHCb has read/write access to lhcbdocs you must behave responsibly and observe its policies! Violators will be banned by librarian from the repository. Report any abuses to the librarian.

Be careful with commands which operate directly on the repository and not on your local copies (svn ci, direct svn cp, svn mv, svn dele etc.).

Respect editing policies defined in README.txt files which are often present in each project directory. Generally stay away from files you did not create unless you are sure you are authorized to change them.

If repository grows too big it will become inefficient or may be completely unusable.

Try to conserve space in the repository.

It is forbidden to use it for other projects than document development (absolutely no data files and code development projects!).

Remember, every file committed to it stays forever there even if you delete it (this is versioned repository which remembers the past). When making a lot of changes, make them in a local copy. Commit to repository only after you are done for a while.

You are encouraged to request your private SVN repository for projects which don't fit the above policies and/or require read/write access restrictions to smaller groups of people. You will find instructions how to do it at:

CERN IT pages.

How to extract LHCb LaTeX document template?

If you want to use LHCb LaTeX document template as a starting point for your document within the repository, copy it from the /Templates/LHCb-latex-template via:

svn cp $DLHCB/Templates/LHCb-latex-template $DLHCB/some-other-path/MyNote  -m"copied template"

If you want to use this template externally, export the template directory into your local directory:

svn export $DLHCB/Templates/LHCb-latex-template/latest MyNote 

and find template files in MyNote/latex/ subdirectory.

You can also downloaded from a web at https://svnweb.cern.ch/cern/wsvn/lhcbdocs/Templates/LHCb-latex-template/latest. Click on "Download" to get a tarbal (.tar.gz file). You can download files one-by-one from https://svnweb.cern.ch/cern/wsvn/lhcbdocs/Templates/LHCb-latex-template/latest/latex directory - double click on the directory name to expend it. You can then click on individual text files to view them.

Say "make" to produce output file (main.pdf) from within the latex/ subdirectory.

Find more info on this template directory by inspecting its README file e.g.

svn cat $DLHCB/Templates/LHCb-latex-template/README.txt | more  

Area for registered LHCb documents

If you have or want to develop a document which already has official LHCb ID numbers (contact the LHCb secretariat), you can put it in /Notes (or /Publications/CERN-EP-PH for papers) areas. E.g. Note LHCb-ANA-2009-011 should be put in /Notes/ANA/2009/011/ location.

If you developed your note in the /Users/ area, use "svn mv" command to move it to the registered notes area.

Users area in lhcbdocs

You are welcome to use lhcbdocs to develop your own documents. You will first need to create your own area in Users/ subdirectory:

svn mkdir $DLHCB/Users/your_user_id -m" "

The above your_user_id should be your lxplus login userid (if you use svn on lxplus you can use $USER for your_user_id).

You must observe policies spelled in here.

It is recommended that you create subdirectories in your area instead of depositing files in your top area. For example:

svn mkdir $DLHCB/Users/$USER/MyDocument1 -m" "

This way you can check out only part of your user area instead of all of it to get to any files (you can check out only directories!) e.g.

svn co $DLHCB/Users/$USER/MyDocument1 

If you are starting new ANA note from scratch in your area which does not have ANA note number assigned (otherwise you should be working under $DLHCB/Notes/ANA/ area), create subdirectory by copying the template

svn cp  $DLHCB/Templates/LHCb-latex-template $DLHCB/Users/$USER/MyANANoteDraft -m" "

which you can later move to the Notes area once you get the note number (e.g. for LHCb-ANA-2009-045):

svn mv $DLHCB/Users/$USER/MyANANoteDraft $DLHCB/Notes/ANA/2009/045   -m" "

Version tagging

Every time you change something in repository global revision number is incremented. In principle, you can use this revision number to identify a version of the document. This number is not human friendly (e.g. 87651). It is a common practice to "tag" versions of the project with human friendly names for future reference.

SVN does not have tag command. Instead, use "svn cp" command to take a snapshot of your development directory to tag directory (this does not create real copies, just references to file revisions, thus it is storage efficient). In svn jargon they are often called "trunk" and "tag" directories respectively. The LHCb templates use "latest" and "drafts" directories for this purpose - we recommend that you stick to this convention. Pre-commit hooks of lhcbdocs prevent modifications to anything put under "drafts" or "tags" directories.

See also tagDoc.py.

Python scripts to help with checking out and tagging of document projects

At present you can get local copies of these scripts via:

svn export $DLHCB/Templates/Scripts/tags/2010-10-24/python . --force

Say "python getDoc.py -help" and "python tagDoc.py -help" to see the usage.

What do I do if I made a mistake and don't know what to do?

The past versions can be restored with "svn cp -revision <#>" command.

If you make a mistake using repository and you don't know how to recover, consult the librarian.

Librarian e-group

To reach lhcbdocs librarian send E-mail to VC-librarians-lhcbdocs at cern (you need to be a member of lhcb-general mailing list to be able to do it).

-- TomaszSkwarnicki - 25-Oct-2010

-- PatrickSKoppenburg - 2018-12-21