Recent changes to Home

Home modified by Geoff Bush

Geoff Bush — Thu, 23 May 2013 19:20:17 -0000

--- v7
+++ v8
@@ -1,5 +1,6 @@
-"RTC_ClearCase_workspace_synchroniser v5.2.2 - released 23rd May 2013
+"RTC ClearCase workspace synchroniser v5.2.2" 
 ==
+Released 23rd May 2013

 The “RTC ClearCase workspace synchroniser“ (synchroniser) is a Linux/UNIX based tactical 
 solution, which allows base ClearCase sub-directory components/products to be

Home modified by Geoff Bush

Geoff Bush — Thu, 23 May 2013 19:19:27 -0000

--- v6
+++ v7
@@ -1,5 +1,5 @@
 "RTC_ClearCase_workspace_synchroniser v5.2.2 - released 23rd May 2013
-=======
+==

 The “RTC ClearCase workspace synchroniser“ (synchroniser) is a Linux/UNIX based tactical 
 solution, which allows base ClearCase sub-directory components/products to be

Home modified by Geoff Bush

Geoff Bush — Thu, 23 May 2013 19:19:13 -0000

--- v5
+++ v6
@@ -1,5 +1,5 @@
 "RTC_ClearCase_workspace_synchroniser v5.2.2 - released 23rd May 2013
-=====================
+=======

 The “RTC ClearCase workspace synchroniser“ (synchroniser) is a Linux/UNIX based tactical 
 solution, which allows base ClearCase sub-directory components/products to be

Home modified by Geoff Bush

Geoff Bush — Thu, 23 May 2013 19:18:56 -0000

<pre>--- v4
+++ v5
@@ -1,1504 +1,8 @@
-"RTC_ClearCase_workspace_synchroniser v5.2.0 - release 16th May 2013
-====================================================================
+"RTC_ClearCase_workspace_synchroniser v5.2.2 - released 23rd May 2013
+=====================
 
 The “RTC ClearCase workspace synchroniser“ (synchroniser) is a Linux/UNIX based tactical 
 solution, which allows base ClearCase sub-directory components/products to be 
-bi-directionally synchronised with RTC source control Components in real-time.
+bi-directionally synchronised with RTC Source Control Components in real-time. It also has 
+the ability to push and pull changes to and from Git Hub repositories.
 
-1. Introduction
-===============
-IBM Rational Team Concert (RTC) uses a separate Jazz SCM component for out-of-the-box
-Software Configuration Management (SCM) and this is packaged under RTC and referred to
-as RTC Source Control. RTC also provides ClearCase connector software that includes a 
-"ClearCase synchroniser", which allows the bi-directionally synchronisation of data
-between the two source control management systems, however, when tested we found that it:
-
-* Requires an exclusive lock of a ClearCase branch, which means existing development 
-branches cannot be used. As such, normalisation of existing branches to a new 
-"synchronisation branch" is required, which introduces an "administration overhead"
-of having to write and run "find merger" scripts to merge changes between the two 
-applications.
-
-* Is not dynamic and has to be run as a scheduled Jazz Build Engine (JBE) task, which is 
-far from ideal as "changes" need to be dynamic.
-
-* Is "ideally" suited to the synchronisation of data that exists in a ClearCase Unified 
-Change Management (UCM) configured windows environment.
-
-2. The "RTC ClearCase workspace synchroniser"
-=============================================
-The "RTC ClearCase workspace synchroniser" (the synchroniser) is a Linux/UNIX based 
-tactical solution written to address the issues highlighted in the introduction. In 
-particular, it allows base ClearCase sub-directory components/products to be 
-bi-directionally synchronised with RTC source control Components in real-time. It also has 
-the ability to bi-directionally synchronise changes with central Git Hub repositories.
-
-Notes:
-i.	The synchroniser runs as a daemon process and deals with changes as and when they 
-occur, obviously, if 1000s of files are added to source control then there will be delays 
-in synchronisation as this amount of data takes time to process.
-ii.	The synchroniser has been successfully stress-tested with many 1000s of files of 
-varying sizes up to an individual file size of 600MB.
-
-3. Glossary
-===========
-CLI  = Command Line Interface
-JBE  = Jazz Build Engine
-JTS  = Jazz Team Server
-MIME = Multimedia Internet Mail Extensions
-POC  = Point Of Contact
-RTC  = Rational Team Concert
-SCM  = Software Configuration Management
-UCM  = Unified Change Management
-URI  = Unique Resource Identifier
-VOB  = Versioned Object Base
-
-4. Overview of the synchroniser core concepts
-=============================================
-The following statements give a brief description of how the synchroniser works for each of 
-the applications (RTC, ClearCase and Git). However, you first need to understand the key 
-concept that the synchroniser uses a RTC Local (sandbox) workspace that is actually located 
-inside a ClearCase snapshot view and that this snapshot view can also host local Git 
-repositories.
-
-ClearCase to RTC source control synchronisation:
-------------------------------------------------
-The synchroniser runs a "cleartool update" for the VOB subdirectory Component in the 
-snapshot view and this identifies any recent changes made in ClearCase.
-
-This activity also creates "Unresolved" changes in the RTC local (sandbox) workspace, which 
-the synchroniser "checks in" to its Repository workspace and then "delivers" to its "Flow 
-Target", RTC Project/Team owned, Stream. 
-
-RTC Project team members who have a Repository Workspace that sources the same Flow Target 
-"Stream" will see the changes as incoming changes Change Sets, which they then "Accept" 
-into their Repository and local (sandbox) workspaces.
-
-RTC to ClearCase synchronisation:
----------------------------------
-The synchroniser "Accepts" incoming "Change Sets" into its Repository workspace. 
-
-This creates changes in the ClearCase snapshot view , which the synchroniser deals with by 
-running the appropriate ClearCase commands to update the underlying ClearCase VOB.
-
-Git to RTC and ClearCase synchronisation:
------------------------------------------
-If activated, the synchroniser "Pulls" changes from a linked "Git Hub" repository into the 
-RTC Local (sandbox)/ClearCase snapshot view workspace. For ClearCase these are dealt with 
-as incoming RTC Source Control Change Sets and for RTC as incoming ClearCase changes.
-
-RTC and ClearCase to Git synchronisation:
------------------------------------------
-If activated, the synchroniser "Pushes" outgoing Component/Product changes from RTC Source 
-Control and ClearCase into the linked Git Hub Repository.
-
-5. Setting up and running a synchroniser instance
-=================================================
-
-5.1. ClearCase information required to create a synchroniser instance
-=====================================================================
-The following ClearCase information is required, from the project area, before you can 
-create a synchroniser instance:
-* The name of the ClearCase VOB(s) where they store their code.
-* The sub-directory location(s) in the VOB(s) that contain the Component(s)/Product(s) that 
-they want to bi-directionally synchronise with RTC source control.
-* The name of the "ClearCase branch" that the Component(s)/Product(s) are currently 
-developed on. Note: This can be the main branch for small teams.
-* A location in a ClearCase VOB from where new Component(s)/Product(s) will be 
-automatically added to the synchronisation process.  
-
-Note: During the setup process any ClearCase VOB sub-directory location can be linked to an 
-RTC Source Control Component, however, once the synchroniser is running it needs a set 
-location from where it can automatically add and the synchroniser centent.
-
-If the need to synchronise a Component/Product outside this location arises then simple 
-stop the synchroniser add then sub-directory manually and then restart the synchroniser. 
-
-5.2. Quick guide to creating a synchroniser instance
-====================================================
-The following is a list of the steps required to create a synchroniser instance.
-
-Note: The quick guide assumes you understand the process and only covers RTC Source 
-Control/ClearCase bi-directional synchronisation. For more information read the "in detail" 
-section:
-
-In ClearCase logged on as the user that will run the synchroniser (vobadm):
----------------------------------------------------------------------------
-1. Create a ClearCase snapshot view where you are advised to use the following naming 
-convention:
-
-  <project>_<activity>_synchroniser_snapshot_view
-
-2. Logon to the ClearCase View server host and proceed as follows:
-  newgrp <VOB primary group>
-  umask 007
-  cd /snapshot_views/<synchroniser_snapshot_view>/vobs
-
-Edit the ClearCase snapshot view config spec adding the appropriate ClearCase branch and 
-load rule(s):
-
-  cleartool edcs
-
-Closing the "cleartool edcs" editor will, if the config spec is correct, load the data into 
-the snapshot view. We then need to ensure that the permissions are correctly set for the 
-newly added data:
-
-  chown -R <user> .
-  chgrp -R <VOB primary group> .
-  chmod -R 770 .
-
-In RTC logged on as the user that will run the synchroniser (vobadm):
----------------------------------------------------------------------
-3. Ensure the user (vobadm) that will run the "synchroniser" is a member of the RTC 
-Project/Team that owns the RTC SCM objects.
-
-4. Identify the RTC Source Control Stream being used for development and if necessary 
-create a new one using the following suggested convention:
-
-  <project>_<branch name>_stream
-
-Ensure the Steam is owned by the RTC Project/Team 
-
-5. For new Component development work:
-
-Add empty Component(s) to the Stream with the same name(s) as the VOB sub-directory 
-Component(s) that exist in ClearCase.
-
-6. For ongoing Component development work:
-
-Baseline the existing Component(s) in the RTC projects current development Stream. Suggest 
-using naming convention:
-
- PRE_<PROJECT>_<ACTIVITY>_BASELINE
-
-Add the existing Component to the new RTC SCM Stream at the Baseline defined above.
-
-7. For both new and ongoing Component development work:
-
-Right-click the Stream and create a new Repository Workspace for use by the synchroniser 
-using the following convention
- vobadm_<project>_<activity>_synchroniser_workspace
-
-In ClearCase logged on as the user that will run the synchroniser (vobadm):
----------------------------------------------------------------------------
-8. Link the ClearCase VOB Component snapshot view data with RTC using "scm share" command.
-  scm -u y -a n share  <workspace_UUID>  <Component_UUID> </snapshot view/VOB pathname to  
-  the Component>/* -r https://<hostname>:9443/ccm -P <password>
-
-Notes: 
-i) the /* needs to be at the end of the Component pathname if the Component contains 
-Eclipse project subdirectories that need to be loaded individually into the Eclipse 
-client.  If the Component root contains directories and files then leave off the /*
-ii). the "scm share" command will have to be run for each Component being linked
-
-9. Run "scm status" to get the status of the workspace. Note: For multiple Components you 
-may have to cd to different locations to do this and this will be the directory location 
-that contains the .jazz5 directory.
-
-10. Depending upon the output and more importantly if this is ongoing development you may 
-need to run "scm checkin" to check in any data updates from ClearCase.  (Note: For multiple 
-Component or even multiple sub-directory locations you may need to run the command from 
-several locations):
-
-  scm checkin -n .
-
-11. Deliver the changes (i.e. the data that has been added by the share activity)
-
-  scm deliver
-
-This will deliver the data changes into the RTC SCM Stream ready for use. (This has to be 
-run from the Component location so may need running several times):
-
-12. Create the synchroniser instance using:
-
- ./rtc_clearcase_workspace_sync --CONFIG
-
-13. Start the synchroniser instance from the control file area with:
-
-  ./sync start
-
-and if everything runs ok create a post import RTC project Component Baseline using the 
-following suggested convention: 
-
- POST_INITIAL_IMPORT_<PROJECT>_<ACTIVITY>_BASELINE
-
-5.3. Synchroniser creation in detail
-====================================
-Note: the following section is based around the ClearCase "vobadm" (VOB Administration 
-account) owning the ClearCase VOB and running the synchroniser process.
-
-In ClearCase:
--------------
-a). Create a ClearCase snapshot view using the following suggested naming convention:
- <project_name>_<activity>_synchroniser_snapshot_view
-
-Note: The naming convention is not mandatory but it makes sense to use a common naming 
-convention. You could also add the Activity if required (i.e. "_pilot_" , "_live_", 
-_maintenance", dev" etc... after the project name if applicable to make the snapshot view 
-more easily recognisable.
-
-b). Logon to the server that hosts the snapshot view and use:
-
-  newgrp <VOB primary group name>
-
-to change the current shells primary group to that of the VOB. Note: If the VOBs primary 
-group is not on the synchroniser users (vobadm) secondary group list then you need to use a 
-utility like "sugrp" to create the correct owner group configuration. So as root run:
-
-  #sugrp <VOB Owner> <VOB primary group>
-
-It also makes sense to set the umask as follows to ensure "rwx" (Read, Write, Execute) for 
-the owner and group but "No" access to others(world):
-
-  umask 007
-
-Update the ClearCase snapshot View "config spec" with the required ClearCase branch 
-information and load rules:
-(Suggestion: Take the config spec the project is currently using to deliver code to their 
-development/integration branch)
-
-  cd /snapshot_views/<synchroniser_snapshot_view>/vobs
-
-Edit the config spec and add the projects ClearCase branch information.  You also need to 
-add the appropriate "load rule/rules" for the Component sub-directory to ensure the correct 
-VOB data gets loaded and subsequently bi-directionally synchronised between RTC source 
-control and ClearCase.  
-
-  cleartool edcs
-
-Example:  
-
-  # Release 5 branch
-  element * CHECKEDOUT
-  element /vobs/samecs_src/... .../synchroniser_rel_5/LATEST
-  element /vobs/samecs_src/... SYNCHRONISER_REL4_BRPT -mkbranch synchroniser_rel_5
-  element /vobs/samecs_src/... /main/0 -mkbranch synchroniser_rel_5
-  # catch all
-  element * /main/LATEST
-  load /vobs/samecs_src/synchroniser
-
-When the "cleartool edcs" editor is closed it will, if the config spec syntax is correct, 
-load the data into the snapshot view. 
-
-c). Update the permissions in the snapshot view
-The objects in the snapshot view need to have consistent permissions before we start 
-synchronising so cd <extended snapshot view/VOB pathname>:
-
-Example:
-
-  cd /snapshot_views/synchroniser_release_5_snapshot_view/ vobs/ samecs_src/synchroniser
-  cleartool update .
-
-Ensure that the permissions are consistent throughout the snapshot view with:
-
-  chown <VOB owner> -R .
-  chgrp <VOB Primary Group>  -R .
-  chmod 770 -R .
-
-d). On the ClearCase View server host that hosts the synchroniser snapshot View ensure a 
-supported version of the RTC Eclipse Client is installed (ideally matches the server) and 
-if necessary add the scmtools location to the $PATH variable.
-
-  export PATH=$PATH:/opt/IBM/TeamConcert/scmtools
-
-Notes: 
-i) Running "cleartool lsview -l -prop -full <snapshot view name> will identify the View 
-server host hosts the View.
-ii) The synchroniser uses the following commands to check for updates in the ClearCase 
-snapshot view:
-
-  # Update the View with what has changed in the VOB
-  cleartool update <Extended snapshot view/VOB/sub-directory Component location>
-  
-  # Check for any hijacked files, which will occur when RTC updates are sent to ClearCase
-  cleartool ls -r -visible . | grep -w hijacked
-  
-  # Check for any new files added in RTC bound for ClearCase
-  cleartool ls -r -visible . | grep -v Rule:
-
-These commands:
-
-  cleartool ls -r -visible . | grep -w hijacked
-  cleartool ls -r -visible . | grep -v Rule:
-
-can be used manually to check the status of the contents of the snapshot view/local  
-workspace that connects RTC Source Control with ClearCase.
-
-In RTC Source Control:
-----------------------
-e). Ensure that the user that runs the synchroniser is a member of the RTC Project/Team. 
-Note: This user has to be able to write to the ClearCase VOB as well so the VOB owner is a 
-good idea (i.e. vobadm ). 
-
-f). If required, create an RTC Project Stream for the development project. (Note: The 
-Project may already have a development Stream that they want to use) 
-
- <project>_<branch name>_stream
-
-again naming not mandatory but it is nice to have a convention.
-
-g). Either, Create a new empty Component(s) in the Stream to match the 
-Component(s)identified in ClearCase
-
-Or, if this is continuing development work for an existing Component under this New stream:
-
-a. Create a baseline of the Component in the existing Stream using the following convention:
-
-  PRE_<PROJECT>_<ACTIVITY>_BASELINE
-
-b. Add the Components(s) at the baseline/baselines created under i. above to the Stream
-
-Notes: 
-1. The name of the Component can be and often are different it is just easier if they 
-match. To date they have tended to differ as projects have used the move to RTC Source 
-Control as an opportunity to refactor.
-
-2. Please ensure that the ownership of the Stream and Component are correctly set to the 
-RTC Project or Team and that the Components access control permissions are correctly set 
-according to the projects requirements (i.e. private, scoped,  public)
-
-h). Create a synchroniser workspace using the following convention:
-
-  <synchroniser_process_user>_<project>>_<activity>_synchroniser_workspace
-
-Notes:
-1. Again naming not mandatory but it is good to have a convention
-2. We are using the "vobadm" process account because it owns the ClearCase VOBs; therefore, 
-there will be no issues when writing data into the VOB via the snapshot view.
-3. In the RTC Eclipse client under the RTC Project Source Control dropdown, as vobadm, 
-right-click the Stream and go New -> Repository Workspace
-4. You do not need to load the Repository Workspace contents into vobadms local workspace 
-as the ClearCase snapshot view will be the local workspace once you have shared in the 
-data. Note: To stop the load uncheck the "load repository workspace" box on the final
-load screen.
-5. If you only want to synchroniser 1 or 2 Components, when many exist in the Stream: you 
-need to "Edit" the Flow Target for the Repository Workspace and select the "Flow only 
-components checked below:" button and then the appropriate Component check box.
- 
-IMPORTANT: You must also create the control file in the synchroniser control files area:
-
-  .stream_workspace_components_differ
-
-In the synchroniser control files area for this to work.
-
-i). Link each Component in the RTC Repository Workspace with the sandbox/ClearCase
-snapshot View VOB subdirectory Component location using the "scm share" command:
-
-  scm -u y -a n share <workspace_UUID> <Component_UUID> <extended snapshot view/VOB  
-  pathname to the Component> -r https://<hostname>:9443/ccm -P <password>
-
-Example:
-  scm -u y -a n share _dBkaEB0fEeKPMLCqm4LCXw _v7lbIBXCEeGWk9R6Iu9Sbg 
-  /snapshot_views/synchroniser_release_5_snapshot_view/vobs/samecs_src/synchroniser/* -r  
-  https://samecs.dev.com:9443/ccm -P xxxx
-
-Notes:
-1. The easiest way to get the WORKSPACE_UUID is as follows:
-
-Open the Eclipse "Team Artefacts" view and go to my Repository Workspace right-click the 
-required Repository Workspace and select Open.  In the window that appears right-click
-the Stream object (top left) and select "Copy URL" and paste the into a text editor
-
-  https://samecs.dev.com:9443/ccm/resource/itemOid/com.ibm.team.scm.Workspace
-  /_1hr8oG3VEeGlA-_5-5kCuQ
-
-The Repository Workspace UUID is the last entry on the line.
-
-2. The easiest way to get the COMPONENT_UUID (and Stream UUID) is as follows:
-
-Open the RTC web client go to the RTC Project -> Source Control and select the Stream and 
-then a Component. If you then copy and paste the URL into a text editor:
-  
- https://samecs.dev.com:9443/ccm/web/projects/End% 
- 20Product#action=com.ibm.team.scm.browseElement&workspaceItemId
- =_BJcY8KvzEeKE8M0emrpgkw&componentItemId=_v7lbIBXCEeGWk9R6Iu9Sbg&path=/
-
-The  COMPONENT_UUID is the last entry on the line and the STREAM_UUID is the one before.
-
-3. Components that contain just Eclipse project sub-directories should be added with an  
-<extended snapshot view/VOB pathname> that ends .../*
-
-  i.e. .../webservices/src/java/*
-
-The will ensure the sub-directories in the Component get loaded as separate Eclipse 
-projects rather than as a single Eclipse project under a root folder in Eclipse.
-
-4.  If there is a directory hierarchy structure in the extended snapshot view/VOB 
-path then add those in the synchronisation root last. Example: 
-
-  .../vobs/samecs/src/webservices/src/java 
-
-before
-
-  .../vobs/samecs/src/webservices/scripts
-
-and
-
-  ... /vobs/samecs/src/webservices/utils)
-
-5. If you do get this wrong then temporarily rename the blocking .jazz5/ directory which 
-will allow the child sharing to go ahead. 
-
-Example:
-  mv ../vobs/samecs/src/webservices/scripts/.jazz5/ ../vobs/samecs/src/webservices/scripts
-  /.jazz5_tmp/
-  
-  scm -u y -a n share ....
-  
-  mv ../vobs/samecs/src/webservices/scripts/.jazz5_tmp/ ../vobs/samecs/src/webservices  
-  /scripts/.jazz5/
-
-j). If this is ongoing development work of an existing Component then "scm share" activity, 
-described above, will result in "Unresolved" changes in the sandbox/Local 
-Workspace/ClearCase snapshot view, which need "checking in" therefore, run:
-  
-  scm checkin -n .
-
-Note: You will need to run this from multiple locations in multiple Components are involved.
-
-k). Deliver the changes that the share you have just run will have created using the "scm 
-deliver" command. 
-  
-  vobadm@scoria$ scm deliver
-  Password (vobadm @ https://samecs.dev.com:9443/ccm/):            
-  Delivering changes:
-   Workspaces:
-    (1184) "vobadm Synchroniser Release synchroniser workspace" --> (1192) "Synchroniser 
-    Release 5"
-      Components:
-        (1193) "Synchroniser"
-
-Note: You will need to run this from multiple locations in multiple Components are involved.
-
-l). Finally check that everything is ok by running and "scm status" command, which should 
-give the following type of output that indicates everything is up to date.
-  vobadm@obsidian$ scm status -v -w
-  Workspace: (1184) "vobadm Synchroniser Release t synchroniser workspace" --> (1192) 
-  "Synchroniser Release 5"
-  Component: (1193) "Synchroniser"
-    Baseline: (1200) 1 "Initial Baseline"
-
-Note: You will need to run this from multiple locations in multiple Components are involved.
-
-Alternative RTC Source Control method
--------------------------------------
-Everything under the section above assumes that the data starts in ClearCase and will be 
-shared/loaded into RTC source control, which is currently the norm. However, it is 
-perfectly acceptable to start with the data in RTC Source Control and share/load this into 
-ClearCase using the following steps:
-
-a). Add the RTC Stream Component to the synchroniser Repository Workspace with:
-
-  scm workspace add-comp <Component_UUID>
-
-b). Accept the new Component into the Repository Workspace with:
-
-  scm accept -C <Component_UUID> 
-
-c). Load the data into the workspace/snapshot view ready to be added to ClearCase:
-
-  scm load --force <workspace_UUID> <new_Component_UUID> -d "<snapshot view new component 
- (parent directory) location>" ...
-
-d). Share the Component with everyone else in the team with:
-
-  scm share <workspace_UUID> <new_Component_UUID>  "<snapshot view new component (parent   
-  directory) location><new_component>"
-
-e). Deliver the Share with:
-
-  scm deliver
-
-The following additional steps will also be required in ClearCase:
-------------------------------------------------------------------
-
-f). Add the view private data in the ClearCase snapshot view to ClearCase source control.
-
-5.4.	Creating a synchroniser instance
-========================================
-
-You create a synchroniser instance by running:
-
-  ./rtc_clearcase_workspace_sync --CONFIG 
-
-in this mode (--CONFIG) the synchroniser will prompt you for the 8 arguments, which are 
-required by the synchroniser at "runtime".
-
-5.4.1. Synchroniser setup - required arguments in the order requested by the synchroniser:
-===========================================================================================
-After checking that the server you are running on is capable of supporting the synchroniser 
-by validating the RTC SCM CLI, the synchroniser will prompt you for the following 8 
-arguments. Note: Argument variable name used by the synchroniser is given in brackets 
-i.e.($LOGPATH):
-
-1.(a) A unique none source control UNIX/Linux directory location ($LOGPATH). 
-
-Note: This should be a file share with both Network File System (NFS) and Common Internet 
-File System (CIFS) access as it used by the synchroniser for control files, which are 
-accessed via both Linux/UNIX and Windows. For SAMECS usages we have defined this to be a 
-subdirectory beneath:
- 
- /snapshot_views/sync/
- 
-(i.e.. /snapshot_views/sync/<project name> )
-
-1.(b) You will then be asked for the CIFS domain name and offered a default 
-(samecs.dev.com), which you can accept by hitting "Return".
-
-From this entry the synchroniser will attempt to calculate the CIFS share equivalent of the 
-UNIX/Linux LOGPATH you entered under 1. (a) 
-
-  (i.e \\samecs.dev.com\snapshot_views\sync\<project-name> )
-
-which you can accept by hitting "Return".
-
-Note: The CIFS share is required by the postop lnname trigger, which runs a Perl script 
-that tracks windows "cleartool mv source target" commands.
-
-2. The synchronisation root directory ($SYNCROOT). 
-
-Notes:
-i) This will be the directory location in the extended ClearCase snapshot view/VOB pathname 
-and should be the highest common point in the directory structure from where all 
-synchronised Component objects in ClearCase can be accessed.
-
-ii) If the synchroniser is synchronising multiple VOBs this will be the .../vobs/... 
-directory.
-
-An example of an extended ClearCase snapshot View/VOB/sub-directory location is given below:
-
-  /snapshot_views/SAMECS_sync_snapshot_view/vobs/SAMECS/jazz/rtc/tech/imp/src
-
-Note: The synchroniser then validates your entry to see it exists before continuing.
-
-3. The Jazz Repository URI of the Jazz Team Server ($REPHOST). You will be offered a 
-default that you can accept by hitting "Return". 
- 
-  (i.e. https://samecs.dev.com:9443/ccm)
-
-4. The administrators email address to which emails issued by the synchroniser can be sent 
-($EMAIL). You will be offered a default that you can accept by hitting "Return".
-
- (i.e. support@samecs.dev.com)
-
-5. The location of the password file that contains the password of the (vobadm) processing 
-user used by the synchroniser ($PASSWDFILE). You will be offered a default that you can 
-accept by hitting "Return".
-
- (i.e. /home/vobadm/vobadm_passwd.txt)
-
-6. The extended ClearCase snapshot View/VOB pathname location where any new Components 
-created in RTC should be created in ClearCase and where any new sub-directories added in 
-ClearCase will result in an RTC Source Control Component of the same name being created. 
-($NEW_COMPONENTS_LOCATION)
-
-Notes:
-a) This will be the same as the $SYNCROOT if you are using a single VOB with Components 
-contained in a single directory and this will be offered as a default that you can accept 
-by hitting "Return".
-b) If you do not want new Components to be synchronised then create a dummy directory in 
-ClearCase (i.e. /vobs/SAMECS/sync_null) and enter this as the New Components location.  
-Likewise in RTC open the vobadm synchroniser workspace and ensure that the Flow Target for 
-the works space is a selected list of Components. (i.e. Open Flow Target Stream and then 
-edit to select the Components you want to synchronise).
-
-At this point the synchroniser will validate this entry to ensure that it is a valid RTC 
-Source Control share location by logging on to the Jazz Team Server (JTS) with the Jazz 
-Repository URI and password you have supplied in arguments 3 and 5.
-
-7. The parent directory location from where the synchroniser will run ($SCRIPT_LOCATION). 
-You will be offered a default that you can accept by hitting "Return". 
-
- (i.e. /snapshot_views/SAMECS_admin _snapshot_view /vobs/SAMECS/jazz/rtc/imp/src
- /rtc_base_clearcase_ workspace_synchronisation)
-
-8. The primary group for the ClearCase VOBs being synchronised ($GROUP). You will be 
-offered a default that you can accept by hitting "Return".
-
-Synchroniser instance creation and configuration
-------------------------------------------------
-Once you have entered the 8th argument the synchroniser will continue the setup and 
-configuration process by:
-
-a). Attempting to calculate he $VOBSROOT location (The part of the in the extended snapshot 
-view/VOB pathname up to and including where ../vobs/... occurs.
-
-  i.e. /snapshot_views/synchroniser_evaluation_snapshot_view/vobs)
-
-which it uses to check the existing triggers on the VOB to see if they could potentially 
-conflict with the running of the synchroniser
-
-For example, if it finds any triggers that use a "clearprompt", which may attempt to 
-interact with the synchroniser, it will display the trigger information and ask if you want 
-to proceed or terminate to allow you to take remedial action (i.e. remove the trigger or 
-set ClearCase environmental variables to stop the trigger interacting with the 
-synchroniser).
-
-Another option would be to add -nuser vobadm so that the trigger does not fire for the 
-synchroniser that is run by the vobadm user.
-
-b). Continuing its setup process and creating the log (.synclog), control and metrics files 
-and applying the ClearCase triggers, etc... that it will need at runtime.
-
-c). Attempting to populate the "components" file, which it does by checking the "scm 
-status" of the extended ClearCase snapshot view/VOB Repository Workspaces for Component 
-entries. At this point you will be prompted to either edit of accept what it has found. It 
-will be presented to you in the format:
-
- <$WORKSPACE_UUID>*<$COMPONENT_UUID>*<Location relative to $SYNCROOT>
-
-and this format is fully explained in section "Control Files and synclog" 
-
-d). Finally, getting the synchroniser to list the "Flow Target" Stream (STREAM_UUID) for 
-the synchroniser Repository Workspace, which it does by listing the Streams.   
-
-Note: The easiest way the Stream_UUID is to open the Eclipse Team Artefacts view, select 
-the drop-down box for the RTC Project and under "Source Control" right-click on the Stream 
-for the synchroniser and select Open.  In the window that appears right-click the Stream 
-object (top left) and select "Copy URL" and paste the into a text editor
-
-  https://samecs.dev.com:9443/ccm/resource/itemOid/com.ibm.team.scm.Workspace
-  /_BJcY8KvzEeKE8M0emrpgkw
-
-The Steam UUID is the last entry on the line.
-
-This completes the synchroniser setup and configuration process and you will be given the 
-option to either start the synchroniser instance or Exit.
-
-  Do you want to start the synchroniser now? Y/N
-
-Notes: 
-i. The synchroniser stores the arguments entered in a file called "config" that is stored 
-in the logs/control files (LOGPATH) location and this file is sourced at runtime and is 
-reused if you rerun the synchroniser with the --CONFIG option:
-
-  ./rtc_clearcase_workspace_sync --CONFIG 
-
-ii. An additional 9th argument of --TEST will run the synchroniser in standalone test mode 
-and this is set a runtime as describe in the "Running a synchroniser instance" section 
-below.
-
-5.5.	Running a synchroniser instance
-========================================
-
-Daemonized script
------------------
-Once you have completed the "rtc_clearcase_workspace_sync --CONFIG" setup process, the 
-synchroniser will use the argument information to build a working synchroniser instance, 
-which can be run as daemon process that is controlled from the logs/control files 
-($LOGPATH) location with:
-
-  ./sync start
-  ./sync restart
-  ./sync stop
-
-Note: We have defined  "/snapshot_views/sync" to be the parent directory control files 
-location and it contains a sub-directory for each synchroniser instance, therefore, by way 
-of example:
-
-  /snapshot_views/sync/synchroniser_evaluation
-
-is the logs/control files location for the synchroniser_evaluation instance of the 
-synchroniser.
-
-Non-Daemonised script
----------------------
-If you run the synchroniser with the following options it runs in a standalone mode and 
-sends its output to the screen as well as the log files. This is a useful option for 
-debugging and use during the infancy of a new synchroniser:
-
-  ./sync start --TEST
-  ./sync restart --TEST
-
-Updating an existing synchroniser instance
-------------------------------------------
-You can also rerun the initial  "rtc_clearcase_workspace_sync --CONFIG" for the 
-synchroniser instance by running:
-
-  ./sync -CONFIG
-
-This will take your initial responses for each of the 8 arguments and prompt you for 
-acceptance or editing, so this is how you would update a synchroniser instance. 
-
-5.6.	Concurrency of the Jazz SCM CLI
-=======================================
-By default Jazz SCM creates a ".jazz-scm" directory in the users (vobadm) home directory, 
-however, if home directories are shared across servers (the default for SAMECS) or if you 
-are running multiple synchroniser on one servers, again something that will happen on 
-SAMECS, then you need to have a per-user local copy of .jazz-scm and this is achieved by 
-the synchroniser by creating a local copy in the following location:
-
-  /tmp/<USER>/<SYNCHRONISER INSTANCE NAME>/.jazz-scm
-
-when copying the .jazz-scm directory structure if there are any references to existing 
-daemon (lscm) CLIs, which are stored in the .jazz-scm/daemons directory, they are deleted.
-
-5.7. Concurrency in general
-===========================
-Concurrency when synchronising applications is a big issue and the synchroniser has been 
-thoroughly tested in this area.  For instance, changing the contents of a file before it is 
-then renamed and moved to a new location, as part of the same operation (Change Set), has 
-been fully tested to ensure it get mirrored correctly between RTC Source Control and 
-ClearCase, as has, updating numerous objects in various sub-directories before then 
-renaming and moving the main parent directory. 
-
-
-Note: Git is not a version control system in the traditional sense and, as such, it relies 
-on file-system commit snapshots and not version deltas; therefore, for instance, the "git 
-mv" command does not actually rename or move a file it basically deletes and then adds a 
-new file so the synchroniser has top mirror this is the same fashion (delete and then add) 
-when synchronising Git with both RTC Source Control and ClearCase
-
-5.8.	Log/Control Files location
-==================================
-The Log/Control Files location is home to the synchroniser logs and a large number of 
-configuration/transient files used by the synchroniser. The following is a list of the most 
-important files:
-
-components
-----------
-The most important control file is the "components" file and the format for the contents of 
-the components file is:
-  <workspace_UUID>*<Component_UUID>*<Component Location>
-Example:
-  _bd3OcC0-EeClbY5-9MLdDw*_wsC0MAdyEeCHkf0O7NsKcg*samecs/releases*/-
-  _bd3OcC0-EeClbY5-9MLdDw*_wsbOsAdyEeCHkf0O7NsKcg*samecs/rpms
-  _bd3OcC0-EeClbY5-9MLdDw*_wtgz0AdyEeCHkf0O7NsKcg*samecs_web/webGuis/website/MajorWeb/*
-  _bd3OcC0-EeClbY5-9MLdDw*_wuS28AdyEeCHkf0O7NsKcg*samecs_web/webGuis/wingdings*/-
-Notes:
-i. The <Component Location> is the Components pathname relative to the synchroniser defined 
-synchronisation root ($SYNCROOT) location in the extended ClearCase snapshot view.
-
-Example:
-Full path to Component si:
- /snapshot_views/synchroniser_release_5_snapshot_view/vobs/samecs_src/synchroniser
-
-$SYNCROOT:
- /snapshot_views/synchroniser_release_5_snapshot_view/vobs/samecs_src/
-
-Component:
- Portal
-
-Component Location:
- src/synchroniser
-
-ii. An additional */- at the end of the line allows the sub-directories of the Component to 
-be loaded as Eclipse projects. This is the standard configuration when the synchroniser is 
-running and new Components are added.
-
-iii. The synchroniser creates a copy of the "components" file called "components_copy", 
-which can be .
-
-iv. in --CONFIG mode the synchroniser attempts to build this file, however, I would advise 
-you review and where necessary edit this file before starting the synchroniser for the 
-first time
-
-defaults
---------
-The synchroniser creates a defaults file based on the "defaults" entries in SECTION 1 of 
-the synchroniser and these are the default values offered to the user when a new 
-synchroniser instance is created.
-
- WINDOWS_DOMAIN="samecs.dev.com"
- JAZZ_URI="https://samecs.dev.com:9443/ccm"
- JAZZ_SCM_CONFIG="/tmp/vobadm/synchroniser_v4_0_2_testing"
- ADMIN_EMAIL="support@samecs.dev.com"
- RETURN_EMAIL_ADDRESS="support@samecs.dev.com"
- EMAIL_RETURN_ADDRESS_FORMATTING=" -- -f "
- CLASSIFICATION_HEADER=""
- CLASSIFICATION_FOOTER=" "
- EMAIL_CLASSIFICATION_SET="YES"
- CONTROL_FILES_PARENT_DIRECTORY_LOCATION="/snapshot_views/sync"
- SNAPSHOT_VIEW_VOB_LOCATION="/snapshot_views/synchroniser_evaluation_snapshot_view/vobs"
- PASSWORD_FILE_LOCATION="/home/vobadm/vobadm_passwd.txt"
- SYNCHRONISER_RUN_FROM_LOCATION="/snapshot_views/samecs_admin/vobs/samecs_src/synchroniser"
- SCRIPT_NAME="rtc_clearcase_workspace_sync"
- EMAIL_USER="support@samecs.dev.com"
- RUNNING_AS_USER="vobadm"
- PRIMARY_GROUP="ngcc_u"
- SCMTOOLS_DEFAULT="/opt/IBM/TeamConcert/scmtools/eclipse"	
- SCMTOOLS_ALTERNATIVE="/opt/IBM/TeamConcertBuild/scmtools/eclipse"
-
-config
-------
-This file, amongst other things, contains a copy of the 8 input argument used by the 
-synchroniser and if the config exists these arguments are sourced and passed back to the 
-synchroniser for reuse when running the following synchroniser configuration commands:
-
-  ./sync --CONFIG
-  ./rtc_clearcase_workspace_sync -CONFIG
-
-An example of a config file is shown below:
-
- LOGPATH="/snapshot_views/sync/synchroniser_v4_0_2_testing*\\\\samecs.dev.co\\snapshot_views
- \\sync\\synchroniser_v4_0_2_testing"
- SYNCROOT="/snapshot_views/rtc_clearcase_workspace_synchroniser_rtc_v4_0_2_testing  
- _snapshot_view/vobs/synchroniser_evaluation"
- REPHOST="https://samecs.dev.com:9443/ccm"
- PASSWDFILE="/home/vobadm/vobadm_passwd.txt"
- NEW_COMPONENTS_LOCATION="/snapshot_views/rtc_clearcase_workspace
- _synchroniser_rtc_v4_0_2_testing_snapshot_view/vobs/synchroniser_evaluation"
- SCRIPT_LOCATION="/releases/rtc"
- GROUP="ccadm_u"
- EMAIL="support@samecs.dev.com -- -f support@samecs.dev.com"
- RETURN_EMAIL_ADDRESS="support@samecs.dev.com"
- EMAIL_RETURN_ADDRESS_FORMATTING=" -- -f "
- CLASSIFICATION_HEADER=" "
- CLASSIFICATION_FOOTER=" "
- EMAIL_CLASSIFICATION_SET="YES"
- EMAIL_USER="support@samecs.dev.com"
- STREAM_UUID="_AfRT4KEZEeKa_tNjWqU9zA"
- SCMTOOLS="/opt/IBM/TeamConcert/scmtools/eclipse"
- STARTING="NO"
- SYNC_BRANCH="rtc_clearcase_workspace_synchroniser_v4.0.2"
- RUNNING_AS_USER="vobadm"
-
-metrics.txt (One at the Component level and one at the synchroniser level)
---------------------------------------------------------------------------
-These, comma delimited, files store metrics information of the synchronisers activities in 
-the following format:
- Date&Time,SynchroniserInstance,Component,Direction,Command,Action,NumberOfFiles,Data,TimeTaken
- 23_06_11@06_53_00:,samecs,Access_products_java,ClearCase->RTC,"scm -u y -a n 
- checkin",---c,28,0,10
- 23_06_11@15_01_36:,samecs,Samecs_elements_cpp,ClearCase->RTC,"scm -u y -a n 
- checkin",--a-,2,4503,12
- 23_06_11@15_28_28:,samecs,Samecs_elements_cpp,ClearCase->RTC,"scm -u y -a n 
- checkin",---c,3,1774,11
- 23_06_11@15_33_26:,samecs,Samecs_elements_lib,ClearCase->RTC,"scm -u y -a n 
- checkin",-dac,30,75266,14
- 23_06_11@15_42_28:,samecs,Access_products_rpms,ClearCase->RTC,"scm -u y -a n 
- checkin",--ac,19,6856920,13
-
-Heading	Description
- Date&Time:		Date (DD_MM_YY) and time (HH_MM_SS) of the activity.
- Synchroniser Instance:	Name of the synchroniser instance
- Component :		The name of the Component being processed
- Direction:	        Either "RTC to ClearCase" or "ClearCase to RTC"
- Command:	        Short description of the command (i.e. scm checkin)
- Action:                A 4 character string highlighting what the command did:
-                            Renamed/Moved	= m---
-                            Deleted		= -d--
-                            Added		= --a-
-                            Changed (updated)	= ---c
- NumberOfFiles	        The number of files being processed.
- Data:	                The amount of data involved in bytes
- Time Taken:	        The time taken for the activity in seconds.
-
-refactor.sh & refactor.pl
--------------------------
-The synchroniser installs a post operational ClearCase VOB trigger on the hidden "lnname" 
-ClearCase command and this allows the synchroniser to track ClearCase refactoring activity. 
-To implement this, the synchroniser creates two scripts: refactor.sh (UNIX/Linux) and 
-refactor.pl (Windows) and the one that runs is dependent upon the end-user environment 
-(UNIX/Linux or Windows). The data collected by the scripts allows the synchroniser to 
-mirror ClearCase refactoring (Rename and Move) activity in RTC Source Control.
-
-Notes: 
-i.Execute permissions must exist on the scripts for the owner, group and others:
- -rwxr-xr-x  1 vobadm samecs     1783 Apr 23 12:06 refactor.pl
- -rwxr-xr-x  1 vobadm samecs      689 Apr 23 12:06 refactor.sh
-ii. The post operational trigger uses the following naming convention:
-  refactor_<STREAM_UUID>
-
-This allows multiple synchroniser to run against the same VOB but on different ClearCase 
-Branches/RTC Source Control Streams.
-
-synclog
--------
-Any meaningful transactions (i.e. cleartool and scm commands that create change) are logged 
-in the synchroniser log, which is called "synclog". You can also turn on a higher level of 
-logging by placing a file named ".full_logging" in the synchroniser instances control file 
-location.  
-
-An example of a log output is give below:
- *********************************************************************
- 03_08_11@10_33_24: Running "scm -u y -a n accept -C rc5 test"
- 03_08_11@10_33_33: (See output below:)
- Repository: https://samecs.dev.com:9443/ccm/
- Workspace: (_8IojcKe8EeCbbt4zvI36Cg) "vobadm_synchroniser_development_workspace"
- Component: (_Sv9Y0L26EeCYhu87w_ih8w) "rc5 test"
- Change sets:
- (_4fY9Ib27EeCYhu87w_ih8w)  ---$ SAMECS <No comment>
- Changes:
- ---c- /rc5 test/level 1 test.sh
- ---c- /rc5 test/Level 1/test.sh
- **********************************************************************
- 03_08_11@10_33_33: The following files are hijacked (See output below):
- level1 test.sh
- ./Level 1/test.sh
- **********************************************************************
-  Running: cleartool co -usehijack | cleartool ci against the above
- **********************************************************************
- 03_08_11@10_33_33: synchroniser metrics generated
- 03_08_11@10_33_33:,synchroniser_development,rc5 test,RTC->ClearCase,"cleartool co 
- -usehijack & ci",---c,2,13652,1
- ********************************************************************** 
-
-5.8.1.	Other control files with a description:
-===============================================
-
-.classpath.ignore & .build.xml.ignore
--------------------------------------
-When created in the control files area it allows different ".classpath" files to exist in 
-both the ClearCase and RTC source control environments. This control file can be set at the 
-synchroniser or individual Component levels.
-
-.clearcase.ignore
------------------
-When created and populated any files named in the ".clearcase.ignore" file are ignored by 
-the synchroniser. This control file can be set at the synchroniser or individual Component 
-levels. Note: This mirrors the functionality of the out-of-the-box .jazzignore used by RTC 
-Source Control.
-
-.clearcase_to_rtc_sync.ignore
------------------------------
-When created, it stops ClearCase updates being sent to RTC source control. This control 
-file can be set at the synchroniser or individual Component levels.
-
-.cli_version
-------------
-Stores the current version of the Jazz SCM CLI and is used by the synchroniser to allow for 
-variance interface. 
-
-.empty
-------
-Identifies the data status of the Component:
-* "NO" indicates that it contains data
-* "YES" indicates that the Component is empty
-
-.full_logging
--------------
-When created in the control files area it turns on a high-level of logging (i.e. list all 
-checkout and checkins rather than a summary). This control file can be set at the 
-synchroniser or individual Component levels.
-
-.get_symlinks
--------------
-RTC Source Control does not fully support symbolic linking; therefore, when created, the 
-.get_symlinks control file lists the ClearCase symbolic links in the VOB sub-directory 
-Component that will not be reflected in RTC Source Control. For each Component the output 
-is sent to the file:
-
-<$LOGPATH>/$COMPONENT_UUID/.symlinks
-
-Note: You should not leave the ".get_symlink" flag turned on permanently as this will 
-affect the performance on the synchroniser.
-
-.git_sync
----------
-If the file exists the synchroniser pushes RTC Source Control and ClearCase changes to a 
-central Git Hub repository (Component). This control file can be set at the synchroniser or 
-individual Component levels.
-
-Note: A number of other steps are required to activate Git synchronisation and these are 
-detailed in  Git synchronisation
-
-.hostname
----------
-This control file contains the "hostname" of the server for the synchroniser instance and 
-ensures that
-* the "./sync stop" and ./sync start" are run on the correct server host.
-* a second instance is not started when one is already running.
-
-.last_run
----------
-A time-stamped control file that is updated by the synchroniser before the processing of 
-each Component begins, which can be used to see if a synchroniser has stopped running.  On 
-SAMECS we run an hourly cronjob of samecs.dev.com, which emails SAMECS  Support if a 
-synchroniser instance has stopped working.
-
-.lscm_override
---------------
-If the Components being synchroniser exist at different ClearCase VOB sub-directory levels 
-then the synchroniser defaults to using individual "scm" commands rather than the standard 
-permanently running "lscm" daemon command. However, you can continue to run the "lscm" 
-daemon as long as the Component pathname do not overlap; therefore, the ".lscm_override" 
-control file was created to allows usage of the "lscm" command in such situations. 
-
-.no_component_rename
---------------------
-By default a Component appears in the components files as a Component that contains Eclipse 
-project sub-directories (i.e. has */-" ending to the line) and, as such, the Component 
-named sub-directory in ClearCase and the RTC Source Control Component are linked; 
-therefore, if one is renamed, say in ClearCase, then it will get renamed in RTC Source 
-Control.  There may be occasions when you want the Component to be renamed in one tool but 
-not in the other so creating the ".no_component_rename" control file, which can be set at 
-the synchroniser or individual Component levels, allows this to happen.
-
-.no_git_pull
------------
-When this file exists in a control files area, it will stop the synchroniser running the 
-"git pull" command that pulls changes from the "Git Hub" repository into the RTC Source 
-Control and ClearCase linked Component. This control file can be set at the synchroniser or 
-individual Component levels.
-
-.no_git_tag
------------
-When this file is exists in a control files area, it will stop the synchroniser running the 
-"git tag" command that mirrors RTC Source Control baseline in the equivalent "Git Hub" 
-linked repository. This control file can be set at the synchroniser or individual Component 
-levels.
-
-.no_label
----------
-By default RTC Source Control created Baselines generate a ClearCase mklbtype followed by a 
-silent mklabel of the equivalent files in ClearCase, however, if the ".no_label" control 
-file, which can be set at the Instance or Component level, exists the labelling activity in 
-ClearCase does not take place.
-
-.poc
-----
-The ".poc" file is designed to hold the email addresses of the RTC Source Control/ClearCase 
-project related Points Of Contact (POCs).  The list should contain members of the project 
-hierarchy that should be emailed if the synchroniser experiences any processing issues. 
-This control file can be set at the synchroniser or individual Component levels.
-
-.rtc_to_clearcase_sync.ignore
------------------------------
-When this control exists it stops RTC Source Control events being sent to ClearCase. This 
-control file can be set at the synchroniser or individual Components level.
-
-Note: This means that the RTC Source Control Change Sets will "backup" in the synchroniser 
-Repository Workspace; therefore, you should monitory the synchroniser instance closely if  
-this control file is removed as it could "open the floodgates" with changes bound for 
-ClearCase, which may take considerable time to process.
-
-.script_run_stop
-This control file contains either the word "run" or "stop" and is populated by the ./sync 
-start|stop|restart script options, where the "./sync stop" option changes the contents to 
-"stop" and causes the synchroniser to terminate after it has processed its current 
-Component.
-
-.sync_branch
-------------
-Stores the name of the ClearCase branch being used by the synchroniser instance.
-
-.stream_workspace_components_differ
------------------------------------
-There are occasions when the synchroniser is only required to synchroniser certain 
-Components in a Stream. If this is the case then you need to create 
-".stream_workspace_components_differ" in the synchroniser instances control files area 
-($LOGPATH)
-
-.version
---------
-This control file stores the version number of the synchroniser that is currently running. 
-It sources its information from $SYNC_VERSION variable which is defined at the beginning of 
-the synchroniser shell script.
-
-5.8.2. Transient files in the control file area
-===============================================
-The synchroniser also creates a large number of transient files that are generated from the 
-"cleartool" and "scm" command outputs and these are used for logging and error trapping 
-purposes. 
-
-6. Synchronising RTC Source Control and ClearCase changes with a Git Hub
-========================================================================
-With effect v5 of the synchroniser RTC Source Control and ClearCase changes can be 
-synchronised with a central Git Hub repository, however, to activate the "git sync" part of 
-the synchroniser there are some administration level tasks that need completing first.
-
-a). Stop the synchroniser instance:
-
- $ cd /snapshot_views/sync/<synchroniser instance>
- $ ./sync stop
-
-b). Change directory to the extended ClearCase snapshot view/VOB/Component Linux operating 
-system location:
-
-For this example the snapshot view location of the "synchroniser_evaluation_ snapshot_view" 
-is:
-
- /snapshot_views/rtc_clearcase_workspace_synchroniser_v4.0.1_snapshot_view
-
-The extended snapshot view/VOB location for the synchroniser_evaluation VOB extends this 
-path to:
-
- /snapshot_views/rtc_clearcase_workspace_synchroniser_v4.0.1_snapshot_vie 
- /vobs/synchroniser_evaluation
-
-And the Component is "Volcano". In this example the Component is located in the root of the 
-VOB giving a final extended snapshot view/VOB/Component pathname of:
-
- /snapshot_views/rtc_clearcase_workspace_synchroniser_v4.0.1_snapshot_view
- /vobs/synchroniser_evaluation/Volcano/
-
-So cd to the extended ClearCase snapshot view/VOB/Component location, which should contain 
-the .jazz5/ RTC Source Control "metadata" directory.
-
- cd /snapshot_views/rtc_clearcase_workspace_synchroniser_  
- v4.0.1_snapshot_view/vobs/synchroniser_evaluation/Volcano/
-
-c). If one does not exist in this location create a .jazzignore file so that we can ignore 
-the Git control files
-
- $ touch .jazzignore
-
-and populate either the existing or new file as follows:
-
- $ echo .git/ >> .jazzignore
- $ echo .gitignore >> .jazzignore
- $ cat .jazzignore
- .git/
- .gitignore
-
-d). If one does not exist in this location create a .gitignore file so that Git can ignore 
-the Jazz control files.
-
- $ touch .gitignore
-
-and populate either the existing or new file as follows:
-
- $ echo .jazz5/ >> .gitignore 
- $ echo .metadata/ >> .gitignore
- $ echo clientdb.xml >> .gitignore
- $ echo .jazzShed/ >> .gitignore
- $ echo .jazzignore >> .gitignore
- $ cat .gitignore
- .jazz5/
- .metadata/
- clientdb.xml
- .jazzShed/
- .jazzignore
-
-e). In the same extended snapshot view/VOB/Component location initialise (create) a local 
-git repository by running:
-
- $ git init
- Initialized empty Git repository  
- in /snapshot_views/rtc_clearcase_workspace_synchroniser_v4.0.1_snapshot_view/vobs/
- synchroniser_evaluation/Volcano/.git
-
-f). Start tracking all the objects in the "Volcano" directory by staging them ready to add 
-to local git repository you have just created by running:
-
- $ git add -- all
-
-Note: The ".gitignore" file tells git to ignore the Jazz related control files
-
-g). Commit the staged files into the local repository by running:
-
- $ git commit -m "Initial Commit"
- [master (root-commit) 23ff378] Initial Commit
- 6 files changed, 79 insertions(+)
- create mode 100644 .gitignore
- create mode 100755 Volcano/.classpath
- create mode 100755 Volcano/.project
- create mode 100755 Volcano/.settings/org.eclipse.jdt.core.prefs
- create mode 100755 Volcano/src/VolcanoApplication.java
- create mode 100755 Volcano/src/VolcanoRobot.java
- $
-
-h). If you have not already created a Git Project and Repository that you are going to link 
-to the RTC Source Control Component/ClearCase sub-directory then logon to the Git Hub 
-Enterprise management tool, create a Project and a Repository that you are going to link to 
-the RTC Source Control Component/ClearCase VOB sub-directory, which in this example is 
-"Volcano". You now need to add the remote Repository using:
-
- $ git remote add Volcano ssh://git@samecs.dev.com:7999/JSGS/volcano.git
-
-Notes: You can check the remotes with:
-
- $ git remote -v
- Volcano ssh://git@samecs.dev.com:7999/JSGS/volcano.git (fetch)
- Volcano ssh://git@samecs.dev.com:7999/JSGS/volcano.git (push)
-
-Component names can be long so if you wanted to shorted the remote repository name to, say, 
-"vol" rather than "Volcano" you can do this by creating an "..git_remote" file in the 
-control files area and populating the file with the shortened name.
-
- cd /snapshot_views/sync/synchroniser_v4.0.1_testing
-
-Cat the components file and get the Component UUID location, which is the entry after the 
-first *:
-
- cat component
- ....
- _RGlAcGrLEeKpwdFSiAVPNQ*_v7TGsHnFEeKpwdFSiAVPNQ*Volcano*/-
- ....
-
-cd to the Component UUID location:
-
- cd *_v7TGsHnFEeKpwdFSiAVPNQ
-
-Touch the .git_remote file and populate with the shortened remote repository name:
-
- touch .git_remote
- echo "vol" > .git_remote
-
-If the remote already exists you can remove this with:
-
- $ git rm Volcano
-
-You can then add the alias to identify the remote with:
-
- $ git remote add vol ssh://git@samecs.dev.com:7999/JSGS/volcano.git
-
-i). Push the data committed to the local repository to the remote Git Hub repository
-
- $ git push Volcano master
- Counting objects: 11, done.
- Delta compression using up to 4 threads.
- Compressing objects: 100% (11/11), done.
- Writing objects: 100% (11/11), 1.68 KiB, done.
- Total 11 (delta 0), reused 0 (delta 0)
- To ssh://git@samecs.dev.com:7999/JSGS/volcano.git
- * [new branch]      master -> master
- $
-
-Notes: 
-1. If there are issues with the RSA key they will be highlighted at this point and can be 
-resolved at this time as well.
-
- The authenticity of host 'samecs.dev.com (192.168.0.10)' can't be established.
- RSA key fingerprint is 01:3c:6c:f6:9e:af:f1:34:38:20:2a:de:b6:79:6b:ca.
- Are you sure you want to continue connecting (yes/no)? yes
- Warning: Permanently added 'samecs.dev.com,192.168.0.10(RSA) to the list of known hosts.
- Counting objects: 11, done.
- Delta compression using up to 4 threads.
- Compressing objects: 100% (11/11), done.
- Writing objects: 100% (11/11), 1.68 KiB, done.
- Total 11 (delta 0), reused 0 (delta 0)
- To ssh://git@samecs.dev.com:7999/JSGS/volcano.git
- * [new branch]      master -> master
- $
-
-2. If you see the following error:
-
- To ssh://git@samecs.dev.com:7999/JSGS/dmoz.git
- ! [rejected]        master -> master (non-fast-forward)
- error: failed to push some refs to 'ssh://git@samecs.dev.com:7999/JSGS/dmoz.git'
- hint: Updates were rejected because the tip of your current branch is behind
- hint: its remote counterpart. Merge the remote changes (e.g. 'git pull')
- hint: before pushing again.
- hint: See the 'Note about fast-forwards' in 'git push --help' for details.
-
-Try the following which will force the changes to be pushed:
-
- $ git push -f Volcano master
-
-j). Check the status of the workspace (i.e. the extended ClearCase snapshot view/VOB
-/Component location) by running:
-
- $ git status
- # On branch master
- nothing to commit (working directory clean)
-
-k). Getting the RTC ClearCase workspace synchroniser to push updates to Git. Cd to the 
-control file area, which will be a sub-directory under:
-
- /snapshot_views/sync
-
-So for this example the directory is:
-
- /snapshot_views/sync/synchroniser_v4.0.1_testing
-
-cat the components file to get the Component UUID, in this case for the Volcano Component:
-
- $ cat components
- _RGlAcGrLEeKpwdFSiAVPNQ*_f5qPsGrKEeKpwdFSiAVPNQ*RTC_Analytics*/-
- _RGlAcGrLEeKpwdFSiAVPNQ*_a0UowXnMEeKpwdFSiAVPNQ*String^Checker^renamed*/-
- _RGlAcGrLEeKpwdFSiAVPNQ*_C8yy8XnMEeKpwdFSiAVPNQ*Weather*/-
- _RGlAcGrLEeKpwdFSiAVPNQ*_v7TGsHnFEeKpwdFSiAVPNQ*Volcano*/-
-
-cd to the Component UUID location, which is the second UUID in the Components file directly 
-before the Component name:
-
- $ cd _v7TGsHnFEeKpwdFSiAVPNQ/
-
-Create the .git_sync file
-
- $ touch .git_sync
-
-Note: If the .git_sync file is left blank then "master" will be assumed.
-
-l). Start the synchroniser by cd ing back to the control files area:
-
- $ cd ..
-
-Start the synchroniser:
-
- ./sync start
-
-Note: If you want to observer the output start the synchroniser as follows:
-
- ./sync start --TEST
-
-6.1. Pulling changes from the Git Hub Repository
-================================================
-By default the synchroniser is configured to pull any changes from the Git Hub Repository 
-into RTC Source Control and ClearCase, however, this is not always required and can be 
-stopped by adding the control file:
-
- .no_git_pull
-
-to the control files area. This control file can be set at the synchroniser or individual 
-Component levels.
-
-6.2. RTC Source Control Component Baseline mirroring to a Git Hub Repository
-============================================================================
-When an RTC Source Control baseline is accepted by the synchroniser, by default, it creates 
-a ClearCase label type based on the Baseline name and then applies it to all the equivalent 
-Component sub-directory files in ClearCase. In addition, if the Component is being 
-synchronised with a Git Hub repository then an equivalent "git tag" will be applied to all 
-the equivalent Component files in the Git Hub repository.
-
-Note: Setting the .no_git_label control file stops the "git tag" operation taking place and 
-setting the  ".no_label" control file stops both the "ClearCase label"  and "git tag" 
-operations.
-
-7. WARNING: Permissions are key dont manually change things in the synchroniser workspace
-=========================================================================================
-Once you have created the jazz scm share you are advised to manually edit anything in that 
-is shown as the black-box synchroniser in the diagram on the next page.  For instance if 
-you manually check out and then check in a file into the VOB from the synchroniser 
-ClearCase snapshot view it will change the files permissions in such a way that the local 
-workspace (sandbox) see this as a change and will create a circular update.
- 
-To reiterate the synchroniser controls this behaviour with the permissions function, where 
-basically the permissions of a file are captured before it is updated and reset back to 
-exactly the same permissions after the update.
-
-Permissions are key to the success of the synchroniser, which ensures files can be written 
-to when they are created or updated in the local workspace (sandbox)/snapshot view 
-location.  
-
-8. Maintenance of the synchroniser and what to do when it goes wrong
-====================================================================
-
-a) The synchroniser is running but is not processing anything.
---------------------------------------------------------------
-Stop the synchroniser "./sync stop" if that does not work run "ps -ef | grep scmtools" and 
-kill the ones that are still running.
-
-Note: If there is an outgoing Change Set with not comment stop the synchroniser cd to the 
-extended snapshot view VOB location and set the Change Set comment with:
-
- scm -u y -a n changeset comment <Change Set UUID> "<suitable comment>"
- scm deliver <Change Set UUID>
-
-b)The synchroniser reports that the "Local file system is out of sync." -- 
---------------------------------------------------------------------------
-*** Run scm load -force <$WORKSPACE_UUID>
------------------------------------------
-
-As the output below highlights in the last line you need to run and scm load -force 
-<WORKSPACE_UUID> < COMPONENT_UUID>
-
- vobadm@jade$ scm status -v -w
- Local filesystem is consistent.
- Password (vobadm @ https://samecs.dev.com:9443/ccm/):            
- Workspace: (0918) "vobadm Synchroniser Release 5 Workspace" <-> (0919) "Synchroniser 
- Release 5"  
- (vobadm @  https://samecs.dev.com:9443/ccm/)
-  Component: (0920) "Synchroniser" <-> (0919) "Synchroniser Release 5"
-    Baseline: (0921) 70 "POST_CLEARCASE_IMPORT_RELEASE_4"
-    Incoming:
-      Change sets:
-        (0935)  ---$ xxxx xxxx 212072 "Modification logic needs to apply when editing saved 
-        draft modification" - <No comment>
-        (0922)  ---$ xxxx xxxx 212366 "Fix wrapping of text for long report titles in 
- Editor LaunchPad  widget" - <No comment>
- ...
- ...
- Some components in (0918) "vobadm Syncroniser Release 5 Workspace" are out of sync.
-    (0920) "Synchroniser"
- Local filesystem is out of sync. Run 'scm load' with --force option to reload the 
- workspace.
-
-Which can be resolved by running "scm load -force <WORKSPACE_UUID>" or for an individual 
-Component with: "scm load -force <WORKSPACE_UUID> <COMPONENT_UUID>"
- vobadm@jade$ scm load --force 0918 0920
- Password (vobadm @ https://samecs.dev.com:9443/ccm/):            
- Downloading /xxxx/.jazzignore  (772 B)
- Downloading /xxx-source.jar  (2.0 KB)
- ...
-Rechecking the status now shows that the synchroniser workspace in now back in sync ready 
-for being used by the synchroniser
- vobadm@jade$ scm status -v -w
- Local filesystem is consistent.
- Password (vobadm @ https://samecs.dev.com:9443/ccm/):            
- Workspace: (0918) "vobadm Synchroniser Release 5 Workspace" <-> (0919) "Synchroniser 
- Release 5" 
- (vobadm @  https://samecs.dev.com:9443/ccm/)
-  Component: (0920) "Synchroniser" <-> (0919) "Synchroniser Release 5"
-    Baseline: (0921) 70 "POST_CLEARCASE_IMPORT_RELEASE_4"
-    Incoming:
-      Change sets:
-        (0935)  ---$ xxxx xxxx 212072 "Modification logic needs to apply when editing 
-         saved draft modification" - <No comment>
-        (0922)  ---$ xxxx xxxx 212366 "Fix wrapping of text for long report titles in
- ....
-
-c) How to do a manual check of a synchroniser instance
-------------------------------------------------------
-First cd to the synchronisation root directory e.g:
- /snapshot_views/rtc_clearcase_workspace_development_snapshot_view
- /vobs/synchroniser_evaluation
-
-or if the Component only contains Eclipse project sub-directories (i.e. the line in the 
-$LOGPATH/components file ends in a /*-) the Component directory e.g:
-
- /snapshot_views/rtc_clearcase_workspace_development_snapshot_vie
- /vobs/synchroniser_evaluation/Volcano
-
-Checking RTC by running:
-
- scm -u y -a n status -v -w
-
-What you are looking for here is the fact that the local workspace is consistent:
- Local filesystem is consistent.
- Workspace: (_N_WRkJN2EeG78qH6aTWnyQ) "vobadm Synchroniser Release 5 synchroniser 
- workspace" <->   
- (_FgOZwG3SEeGlA-_5-5kCuQ) "Synchroniser Release 5"  (vobadm @ https://samecs.dev.com:9443
- /ccm/)
- Component: (_v7lbIBXCEeGWk9R6Iu9Sbg) "Synchroniser" <-> (_FgOZwG3SEeGlA-_5-5kCuQ) 
- "Synchroniser Release 5"
- Baseline: (_bljPcpOgEeG78qH6aTWnyQ) 33 "POST_SYNCHRONISER_REL_4"
-Note: The synchroniser uses the following commands to check for updates in the ClearCase 
-snapshot view:
-
- # Update the View with what has changed in the VOB
- cleartool update <Extended snapshot view/VOB/sub-directory Component location>
-
- # Check for any hijacked files, which will occur when RTC updates are sent to ClearCase
- cleartool ls -r -visible . | grep -w hijacked
-
- # Check for any new files added in RTC bound for ClearCase
-
- cleartool ls -r -visible . | grep -v Rule:
-
-These commands can be used to check the status of the contents of the snapshot view 
-workspace that connects RTC source control and ClearCase
-
-d) The synchroniser has incorrectly delivered a Change Set
-----------------------------------------------------------
-If the synchroniser has incorrectly delivered changes fro ClearCase to RTC then, as a RTC 
-Project team member open the Jazz SCM Pending Changes view accept the incoming Change Set 
-then open the Component History in the Pending Changes View and reverse the Change Set you 
-have just received.  This will create a patch that should be merged with the workspace, 
-which will reverse the Changes and this should then be delivered to the rest of the 
-Projects Team members.
-
-e) Using the RTC Eclipse client GUI to resolve issues in local (sandbox) workspace
------------------------------------------------------------------------------------
-It is perfectly acceptable to stop the synchroniser and start the RTC Eclipse client GUI as 
-vobadm to resolve any conflict issues:
-
-	/opt/IBM/TeamConcert/Eclipse
-
-Note: If the synchroniser has been running the "lscm" daemonised CLI it will continue to 
-run once you have stopped the synchroniser. To rectify this run:
-
-ps -ef | grep scm
-
-vobadm     418     1  0 07:11 pts/1    00:00:08 /opt/IBM/TeamConcert/scmtools/eclipse/scm 
---config /home/vobadm/.jazz-scm daemon start --connection-timeout 120000 --inactive-timeout 
-7200000
-
-and kill the process#
-
-f) A synchroniser instance will not start but no process is running to kill
----------------------------------------------------------------------------
-The issue was resolved when I removed the /tmp/vobadm/<synchroniser name>/.jazz-scm instance
-
</pre>

Home modified by Geoff Bush

Geoff Bush — Sat, 18 May 2013 19:58:21 -0000

--- v3
+++ v4
@@ -1,3 +1,6 @@
+"RTC_ClearCase_workspace_synchroniser v5.2.0 - release 16th May 2013
+====================================================================
+
 The “RTC ClearCase workspace synchroniser“ (synchroniser) is a Linux/UNIX based tactical 
 solution, which allows base ClearCase sub-directory components/products to be 
 bi-directionally synchronised with RTC source control Components in real-time.

Home modified by Geoff Bush

Geoff Bush — Thu, 16 May 2013 21:03:01 -0000

--- v2
+++ v3
@@ -1,4 +1,6 @@
-The “RTC ClearCase workspace synchroniser“ (synchroniser) is a Linux/UNIX based tactical solution, which allows base ClearCase sub-directory components/products to be bi-directionally synchronised with RTC source control Components in real-time.
+The “RTC ClearCase workspace synchroniser“ (synchroniser) is a Linux/UNIX based tactical 
+solution, which allows base ClearCase sub-directory components/products to be 
+bi-directionally synchronised with RTC source control Components in real-time.

 1. Introduction
 ===============

Home modified by Geoff Bush

Geoff Bush — Thu, 16 May 2013 21:02:36 -0000

<pre>--- v1
+++ v2
@@ -1 +1,1499 @@
 The “RTC ClearCase workspace synchroniser“ (synchroniser) is a Linux/UNIX based tactical solution, which allows base ClearCase sub-directory components/products to be bi-directionally synchronised with RTC source control Components in real-time.
+
+1. Introduction
+===============
+IBM Rational Team Concert (RTC) uses a separate Jazz SCM component for out-of-the-box
+Software Configuration Management (SCM) and this is packaged under RTC and referred to
+as RTC Source Control. RTC also provides ClearCase connector software that includes a 
+"ClearCase synchroniser", which allows the bi-directionally synchronisation of data
+between the two source control management systems, however, when tested we found that it:
+
+* Requires an exclusive lock of a ClearCase branch, which means existing development 
+branches cannot be used. As such, normalisation of existing branches to a new 
+"synchronisation branch" is required, which introduces an "administration overhead"
+of having to write and run "find merger" scripts to merge changes between the two 
+applications.
+
+* Is not dynamic and has to be run as a scheduled Jazz Build Engine (JBE) task, which is 
+far from ideal as "changes" need to be dynamic.
+
+* Is "ideally" suited to the synchronisation of data that exists in a ClearCase Unified 
+Change Management (UCM) configured windows environment.
+
+2. The "RTC ClearCase workspace synchroniser"
+=============================================
+The "RTC ClearCase workspace synchroniser" (the synchroniser) is a Linux/UNIX based 
+tactical solution written to address the issues highlighted in the introduction. In 
+particular, it allows base ClearCase sub-directory components/products to be 
+bi-directionally synchronised with RTC source control Components in real-time. It also has 
+the ability to bi-directionally synchronise changes with central Git Hub repositories.
+
+Notes:
+i.	The synchroniser runs as a daemon process and deals with changes as and when they 
+occur, obviously, if 1000s of files are added to source control then there will be delays 
+in synchronisation as this amount of data takes time to process.
+ii.	The synchroniser has been successfully stress-tested with many 1000s of files of 
+varying sizes up to an individual file size of 600MB.
+
+3. Glossary
+===========
+CLI  = Command Line Interface
+JBE  = Jazz Build Engine
+JTS  = Jazz Team Server
+MIME = Multimedia Internet Mail Extensions
+POC  = Point Of Contact
+RTC  = Rational Team Concert
+SCM  = Software Configuration Management
+UCM  = Unified Change Management
+URI  = Unique Resource Identifier
+VOB  = Versioned Object Base
+
+4. Overview of the synchroniser core concepts
+=============================================
+The following statements give a brief description of how the synchroniser works for each of 
+the applications (RTC, ClearCase and Git). However, you first need to understand the key 
+concept that the synchroniser uses a RTC Local (sandbox) workspace that is actually located 
+inside a ClearCase snapshot view and that this snapshot view can also host local Git 
+repositories.
+
+ClearCase to RTC source control synchronisation:
+------------------------------------------------
+The synchroniser runs a "cleartool update" for the VOB subdirectory Component in the 
+snapshot view and this identifies any recent changes made in ClearCase.
+
+This activity also creates "Unresolved" changes in the RTC local (sandbox) workspace, which 
+the synchroniser "checks in" to its Repository workspace and then "delivers" to its "Flow 
+Target", RTC Project/Team owned, Stream. 
+
+RTC Project team members who have a Repository Workspace that sources the same Flow Target 
+"Stream" will see the changes as incoming changes Change Sets, which they then "Accept" 
+into their Repository and local (sandbox) workspaces.
+
+RTC to ClearCase synchronisation:
+---------------------------------
+The synchroniser "Accepts" incoming "Change Sets" into its Repository workspace. 
+
+This creates changes in the ClearCase snapshot view , which the synchroniser deals with by 
+running the appropriate ClearCase commands to update the underlying ClearCase VOB.
+
+Git to RTC and ClearCase synchronisation:
+-----------------------------------------
+If activated, the synchroniser "Pulls" changes from a linked "Git Hub" repository into the 
+RTC Local (sandbox)/ClearCase snapshot view workspace. For ClearCase these are dealt with 
+as incoming RTC Source Control Change Sets and for RTC as incoming ClearCase changes.
+
+RTC and ClearCase to Git synchronisation:
+-----------------------------------------
+If activated, the synchroniser "Pushes" outgoing Component/Product changes from RTC Source 
+Control and ClearCase into the linked Git Hub Repository.
+
+5. Setting up and running a synchroniser instance
+=================================================
+
+5.1. ClearCase information required to create a synchroniser instance
+=====================================================================
+The following ClearCase information is required, from the project area, before you can 
+create a synchroniser instance:
+* The name of the ClearCase VOB(s) where they store their code.
+* The sub-directory location(s) in the VOB(s) that contain the Component(s)/Product(s) that 
+they want to bi-directionally synchronise with RTC source control.
+* The name of the "ClearCase branch" that the Component(s)/Product(s) are currently 
+developed on. Note: This can be the main branch for small teams.
+* A location in a ClearCase VOB from where new Component(s)/Product(s) will be 
+automatically added to the synchronisation process.  
+
+Note: During the setup process any ClearCase VOB sub-directory location can be linked to an 
+RTC Source Control Component, however, once the synchroniser is running it needs a set 
+location from where it can automatically add and the synchroniser centent.
+
+If the need to synchronise a Component/Product outside this location arises then simple 
+stop the synchroniser add then sub-directory manually and then restart the synchroniser. 
+
+5.2. Quick guide to creating a synchroniser instance
+====================================================
+The following is a list of the steps required to create a synchroniser instance.
+
+Note: The quick guide assumes you understand the process and only covers RTC Source 
+Control/ClearCase bi-directional synchronisation. For more information read the "in detail" 
+section:
+
+In ClearCase logged on as the user that will run the synchroniser (vobadm):
+---------------------------------------------------------------------------
+1. Create a ClearCase snapshot view where you are advised to use the following naming 
+convention:
+
+  <project>_<activity>_synchroniser_snapshot_view
+
+2. Logon to the ClearCase View server host and proceed as follows:
+  newgrp <VOB primary group>
+  umask 007
+  cd /snapshot_views/<synchroniser_snapshot_view>/vobs
+
+Edit the ClearCase snapshot view config spec adding the appropriate ClearCase branch and 
+load rule(s):
+
+  cleartool edcs
+
+Closing the "cleartool edcs" editor will, if the config spec is correct, load the data into 
+the snapshot view. We then need to ensure that the permissions are correctly set for the 
+newly added data:
+
+  chown -R <user> .
+  chgrp -R <VOB primary group> .
+  chmod -R 770 .
+
+In RTC logged on as the user that will run the synchroniser (vobadm):
+---------------------------------------------------------------------
+3. Ensure the user (vobadm) that will run the "synchroniser" is a member of the RTC 
+Project/Team that owns the RTC SCM objects.
+
+4. Identify the RTC Source Control Stream being used for development and if necessary 
+create a new one using the following suggested convention:
+
+  <project>_<branch name>_stream
+
+Ensure the Steam is owned by the RTC Project/Team 
+
+5. For new Component development work:
+
+Add empty Component(s) to the Stream with the same name(s) as the VOB sub-directory 
+Component(s) that exist in ClearCase.
+
+6. For ongoing Component development work:
+
+Baseline the existing Component(s) in the RTC projects current development Stream. Suggest 
+using naming convention:
+
+ PRE_<PROJECT>_<ACTIVITY>_BASELINE
+
+Add the existing Component to the new RTC SCM Stream at the Baseline defined above.
+
+7. For both new and ongoing Component development work:
+
+Right-click the Stream and create a new Repository Workspace for use by the synchroniser 
+using the following convention
+ vobadm_<project>_<activity>_synchroniser_workspace
+
+In ClearCase logged on as the user that will run the synchroniser (vobadm):
+---------------------------------------------------------------------------
+8. Link the ClearCase VOB Component snapshot view data with RTC using "scm share" command.
+  scm -u y -a n share  <workspace_UUID>  <Component_UUID> </snapshot view/VOB pathname to  
+  the Component>/* -r https://<hostname>:9443/ccm -P <password>
+
+Notes: 
+i) the /* needs to be at the end of the Component pathname if the Component contains 
+Eclipse project subdirectories that need to be loaded individually into the Eclipse 
+client.  If the Component root contains directories and files then leave off the /*
+ii). the "scm share" command will have to be run for each Component being linked
+
+9. Run "scm status" to get the status of the workspace. Note: For multiple Components you 
+may have to cd to different locations to do this and this will be the directory location 
+that contains the .jazz5 directory.
+
+10. Depending upon the output and more importantly if this is ongoing development you may 
+need to run "scm checkin" to check in any data updates from ClearCase.  (Note: For multiple 
+Component or even multiple sub-directory locations you may need to run the command from 
+several locations):
+
+  scm checkin -n .
+
+11. Deliver the changes (i.e. the data that has been added by the share activity)
+
+  scm deliver
+
+This will deliver the data changes into the RTC SCM Stream ready for use. (This has to be 
+run from the Component location so may need running several times):
+
+12. Create the synchroniser instance using:
+
+ ./rtc_clearcase_workspace_sync --CONFIG
+
+13. Start the synchroniser instance from the control file area with:
+
+  ./sync start
+
+and if everything runs ok create a post import RTC project Component Baseline using the 
+following suggested convention: 
+
+ POST_INITIAL_IMPORT_<PROJECT>_<ACTIVITY>_BASELINE
+
+5.3. Synchroniser creation in detail
+====================================
+Note: the following section is based around the ClearCase "vobadm" (VOB Administration 
+account) owning the ClearCase VOB and running the synchroniser process.
+
+In ClearCase:
+-------------
+a). Create a ClearCase snapshot view using the following suggested naming convention:
+ <project_name>_<activity>_synchroniser_snapshot_view
+
+Note: The naming convention is not mandatory but it makes sense to use a common naming 
+convention. You could also add the Activity if required (i.e. "_pilot_" , "_live_", 
+_maintenance", dev" etc... after the project name if applicable to make the snapshot view 
+more easily recognisable.
+
+b). Logon to the server that hosts the snapshot view and use:
+
+  newgrp <VOB primary group name>
+
+to change the current shells primary group to that of the VOB. Note: If the VOBs primary 
+group is not on the synchroniser users (vobadm) secondary group list then you need to use a 
+utility like "sugrp" to create the correct owner group configuration. So as root run:
+
+  #sugrp <VOB Owner> <VOB primary group>
+
+It also makes sense to set the umask as follows to ensure "rwx" (Read, Write, Execute) for 
+the owner and group but "No" access to others(world):
+
+  umask 007
+
+Update the ClearCase snapshot View "config spec" with the required ClearCase branch 
+information and load rules:
+(Suggestion: Take the config spec the project is currently using to deliver code to their 
+development/integration branch)
+
+  cd /snapshot_views/<synchroniser_snapshot_view>/vobs
+
+Edit the config spec and add the projects ClearCase branch information.  You also need to 
+add the appropriate "load rule/rules" for the Component sub-directory to ensure the correct 
+VOB data gets loaded and subsequently bi-directionally synchronised between RTC source 
+control and ClearCase.  
+
+  cleartool edcs
+
+Example:  
+
+  # Release 5 branch
+  element * CHECKEDOUT
+  element /vobs/samecs_src/... .../synchroniser_rel_5/LATEST
+  element /vobs/samecs_src/... SYNCHRONISER_REL4_BRPT -mkbranch synchroniser_rel_5
+  element /vobs/samecs_src/... /main/0 -mkbranch synchroniser_rel_5
+  # catch all
+  element * /main/LATEST
+  load /vobs/samecs_src/synchroniser
+
+When the "cleartool edcs" editor is closed it will, if the config spec syntax is correct, 
+load the data into the snapshot view. 
+
+c). Update the permissions in the snapshot view
+The objects in the snapshot view need to have consistent permissions before we start 
+synchronising so cd <extended snapshot view/VOB pathname>:
+
+Example:
+
+  cd /snapshot_views/synchroniser_release_5_snapshot_view/ vobs/ samecs_src/synchroniser
+  cleartool update .
+
+Ensure that the permissions are consistent throughout the snapshot view with:
+
+  chown <VOB owner> -R .
+  chgrp <VOB Primary Group>  -R .
+  chmod 770 -R .
+
+d). On the ClearCase View server host that hosts the synchroniser snapshot View ensure a 
+supported version of the RTC Eclipse Client is installed (ideally matches the server) and 
+if necessary add the scmtools location to the $PATH variable.
+
+  export PATH=$PATH:/opt/IBM/TeamConcert/scmtools
+
+Notes: 
+i) Running "cleartool lsview -l -prop -full <snapshot view name> will identify the View 
+server host hosts the View.
+ii) The synchroniser uses the following commands to check for updates in the ClearCase 
+snapshot view:
+
+  # Update the View with what has changed in the VOB
+  cleartool update <Extended snapshot view/VOB/sub-directory Component location>
+  
+  # Check for any hijacked files, which will occur when RTC updates are sent to ClearCase
+  cleartool ls -r -visible . | grep -w hijacked
+  
+  # Check for any new files added in RTC bound for ClearCase
+  cleartool ls -r -visible . | grep -v Rule:
+
+These commands:
+
+  cleartool ls -r -visible . | grep -w hijacked
+  cleartool ls -r -visible . | grep -v Rule:
+
+can be used manually to check the status of the contents of the snapshot view/local  
+workspace that connects RTC Source Control with ClearCase.
+
+In RTC Source Control:
+----------------------
+e). Ensure that the user that runs the synchroniser is a member of the RTC Project/Team. 
+Note: This user has to be able to write to the ClearCase VOB as well so the VOB owner is a 
+good idea (i.e. vobadm ). 
+
+f). If required, create an RTC Project Stream for the development project. (Note: The 
+Project may already have a development Stream that they want to use) 
+
+ <project>_<branch name>_stream
+
+again naming not mandatory but it is nice to have a convention.
+
+g). Either, Create a new empty Component(s) in the Stream to match the 
+Component(s)identified in ClearCase
+
+Or, if this is continuing development work for an existing Component under this New stream:
+
+a. Create a baseline of the Component in the existing Stream using the following convention:
+
+  PRE_<PROJECT>_<ACTIVITY>_BASELINE
+
+b. Add the Components(s) at the baseline/baselines created under i. above to the Stream
+
+Notes: 
+1. The name of the Component can be and often are different it is just easier if they 
+match. To date they have tended to differ as projects have used the move to RTC Source 
+Control as an opportunity to refactor.
+
+2. Please ensure that the ownership of the Stream and Component are correctly set to the 
+RTC Project or Team and that the Components access control permissions are correctly set 
+according to the projects requirements (i.e. private, scoped,  public)
+
+h). Create a synchroniser workspace using the following convention:
+
+  <synchroniser_process_user>_<project>>_<activity>_synchroniser_workspace
+
+Notes:
+1. Again naming not mandatory but it is good to have a convention
+2. We are using the "vobadm" process account because it owns the ClearCase VOBs; therefore, 
+there will be no issues when writing data into the VOB via the snapshot view.
+3. In the RTC Eclipse client under the RTC Project Source Control dropdown, as vobadm, 
+right-click the Stream and go New -> Repository Workspace
+4. You do not need to load the Repository Workspace contents into vobadms local workspace 
+as the ClearCase snapshot view will be the local workspace once you have shared in the 
+data. Note: To stop the load uncheck the "load repository workspace" box on the final
+load screen.
+5. If you only want to synchroniser 1 or 2 Components, when many exist in the Stream: you 
+need to "Edit" the Flow Target for the Repository Workspace and select the "Flow only 
+components checked below:" button and then the appropriate Component check box.
+ 
+IMPORTANT: You must also create the control file in the synchroniser control files area:
+
+  .stream_workspace_components_differ
+
+In the synchroniser control files area for this to work.
+
+i). Link each Component in the RTC Repository Workspace with the sandbox/ClearCase
+snapshot View VOB subdirectory Component location using the "scm share" command:
+
+  scm -u y -a n share <workspace_UUID> <Component_UUID> <extended snapshot view/VOB  
+  pathname to the Component> -r https://<hostname>:9443/ccm -P <password>
+
+Example:
+  scm -u y -a n share _dBkaEB0fEeKPMLCqm4LCXw _v7lbIBXCEeGWk9R6Iu9Sbg 
+  /snapshot_views/synchroniser_release_5_snapshot_view/vobs/samecs_src/synchroniser/* -r  
+  https://samecs.dev.com:9443/ccm -P xxxx
+
+Notes:
+1. The easiest way to get the WORKSPACE_UUID is as follows:
+
+Open the Eclipse "Team Artefacts" view and go to my Repository Workspace right-click the 
+required Repository Workspace and select Open.  In the window that appears right-click
+the Stream object (top left) and select "Copy URL" and paste the into a text editor
+
+  https://samecs.dev.com:9443/ccm/resource/itemOid/com.ibm.team.scm.Workspace
+  /_1hr8oG3VEeGlA-_5-5kCuQ
+
+The Repository Workspace UUID is the last entry on the line.
+
+2. The easiest way to get the COMPONENT_UUID (and Stream UUID) is as follows:
+
+Open the RTC web client go to the RTC Project -> Source Control and select the Stream and 
+then a Component. If you then copy and paste the URL into a text editor:
+  
+ https://samecs.dev.com:9443/ccm/web/projects/End% 
+ 20Product#action=com.ibm.team.scm.browseElement&workspaceItemId
+ =_BJcY8KvzEeKE8M0emrpgkw&componentItemId=_v7lbIBXCEeGWk9R6Iu9Sbg&path=/
+
+The  COMPONENT_UUID is the last entry on the line and the STREAM_UUID is the one before.
+
+3. Components that contain just Eclipse project sub-directories should be added with an  
+<extended snapshot view/VOB pathname> that ends .../*
+
+  i.e. .../webservices/src/java/*
+
+The will ensure the sub-directories in the Component get loaded as separate Eclipse 
+projects rather than as a single Eclipse project under a root folder in Eclipse.
+
+4.  If there is a directory hierarchy structure in the extended snapshot view/VOB 
+path then add those in the synchronisation root last. Example: 
+
+  .../vobs/samecs/src/webservices/src/java 
+
+before
+
+  .../vobs/samecs/src/webservices/scripts
+
+and
+
+  ... /vobs/samecs/src/webservices/utils)
+
+5. If you do get this wrong then temporarily rename the blocking .jazz5/ directory which 
+will allow the child sharing to go ahead. 
+
+Example:
+  mv ../vobs/samecs/src/webservices/scripts/.jazz5/ ../vobs/samecs/src/webservices/scripts
+  /.jazz5_tmp/
+  
+  scm -u y -a n share ....
+  
+  mv ../vobs/samecs/src/webservices/scripts/.jazz5_tmp/ ../vobs/samecs/src/webservices  
+  /scripts/.jazz5/
+
+j). If this is ongoing development work of an existing Component then "scm share" activity, 
+described above, will result in "Unresolved" changes in the sandbox/Local 
+Workspace/ClearCase snapshot view, which need "checking in" therefore, run:
+  
+  scm checkin -n .
+
+Note: You will need to run this from multiple locations in multiple Components are involved.
+
+k). Deliver the changes that the share you have just run will have created using the "scm 
+deliver" command. 
+  
+  vobadm@scoria$ scm deliver
+  Password (vobadm @ https://samecs.dev.com:9443/ccm/):            
+  Delivering changes:
+   Workspaces:
+    (1184) "vobadm Synchroniser Release synchroniser workspace" --> (1192) "Synchroniser 
+    Release 5"
+      Components:
+        (1193) "Synchroniser"
+
+Note: You will need to run this from multiple locations in multiple Components are involved.
+
+l). Finally check that everything is ok by running and "scm status" command, which should 
+give the following type of output that indicates everything is up to date.
+  vobadm@obsidian$ scm status -v -w
+  Workspace: (1184) "vobadm Synchroniser Release t synchroniser workspace" --> (1192) 
+  "Synchroniser Release 5"
+  Component: (1193) "Synchroniser"
+    Baseline: (1200) 1 "Initial Baseline"
+
+Note: You will need to run this from multiple locations in multiple Components are involved.
+
+Alternative RTC Source Control method
+-------------------------------------
+Everything under the section above assumes that the data starts in ClearCase and will be 
+shared/loaded into RTC source control, which is currently the norm. However, it is 
+perfectly acceptable to start with the data in RTC Source Control and share/load this into 
+ClearCase using the following steps:
+
+a). Add the RTC Stream Component to the synchroniser Repository Workspace with:
+
+  scm workspace add-comp <Component_UUID>
+
+b). Accept the new Component into the Repository Workspace with:
+
+  scm accept -C <Component_UUID> 
+
+c). Load the data into the workspace/snapshot view ready to be added to ClearCase:
+
+  scm load --force <workspace_UUID> <new_Component_UUID> -d "<snapshot view new component 
+ (parent directory) location>" ...
+
+d). Share the Component with everyone else in the team with:
+
+  scm share <workspace_UUID> <new_Component_UUID>  "<snapshot view new component (parent   
+  directory) location><new_component>"
+
+e). Deliver the Share with:
+
+  scm deliver
+
+The following additional steps will also be required in ClearCase:
+------------------------------------------------------------------
+
+f). Add the view private data in the ClearCase snapshot view to ClearCase source control.
+
+5.4.	Creating a synchroniser instance
+========================================
+
+You create a synchroniser instance by running:
+
+  ./rtc_clearcase_workspace_sync --CONFIG 
+
+in this mode (--CONFIG) the synchroniser will prompt you for the 8 arguments, which are 
+required by the synchroniser at "runtime".
+
+5.4.1. Synchroniser setup - required arguments in the order requested by the synchroniser:
+===========================================================================================
+After checking that the server you are running on is capable of supporting the synchroniser 
+by validating the RTC SCM CLI, the synchroniser will prompt you for the following 8 
+arguments. Note: Argument variable name used by the synchroniser is given in brackets 
+i.e.($LOGPATH):
+
+1.(a) A unique none source control UNIX/Linux directory location ($LOGPATH). 
+
+Note: This should be a file share with both Network File System (NFS) and Common Internet 
+File System (CIFS) access as it used by the synchroniser for control files, which are 
+accessed via both Linux/UNIX and Windows. For SAMECS usages we have defined this to be a 
+subdirectory beneath:
+ 
+ /snapshot_views/sync/
+ 
+(i.e.. /snapshot_views/sync/<project name> )
+
+1.(b) You will then be asked for the CIFS domain name and offered a default 
+(samecs.dev.com), which you can accept by hitting "Return".
+
+From this entry the synchroniser will attempt to calculate the CIFS share equivalent of the 
+UNIX/Linux LOGPATH you entered under 1. (a) 
+
+  (i.e \\samecs.dev.com\snapshot_views\sync\<project-name> )
+
+which you can accept by hitting "Return".
+
+Note: The CIFS share is required by the postop lnname trigger, which runs a Perl script 
+that tracks windows "cleartool mv source target" commands.
+
+2. The synchronisation root directory ($SYNCROOT). 
+
+Notes:
+i) This will be the directory location in the extended ClearCase snapshot view/VOB pathname 
+and should be the highest common point in the directory structure from where all 
+synchronised Component objects in ClearCase can be accessed.
+
+ii) If the synchroniser is synchronising multiple VOBs this will be the .../vobs/... 
+directory.
+
+An example of an extended ClearCase snapshot View/VOB/sub-directory location is given below:
+
+  /snapshot_views/SAMECS_sync_snapshot_view/vobs/SAMECS/jazz/rtc/tech/imp/src
+
+Note: The synchroniser then validates your entry to see it exists before continuing.
+
+3. The Jazz Repository URI of the Jazz Team Server ($REPHOST). You will be offered a 
+default that you can accept by hitting "Return". 
+ 
+  (i.e. https://samecs.dev.com:9443/ccm)
+
+4. The administrators email address to which emails issued by the synchroniser can be sent 
+($EMAIL). You will be offered a default that you can accept by hitting "Return".
+
+ (i.e. support@samecs.dev.com)
+
+5. The location of the password file that contains the password of the (vobadm) processing 
+user used by the synchroniser ($PASSWDFILE). You will be offered a default that you can 
+accept by hitting "Return".
+
+ (i.e. /home/vobadm/vobadm_passwd.txt)
+
+6. The extended ClearCase snapshot View/VOB pathname location where any new Components 
+created in RTC should be created in ClearCase and where any new sub-directories added in 
+ClearCase will result in an RTC Source Control Component of the same name being created. 
+($NEW_COMPONENTS_LOCATION)
+
+Notes:
+a) This will be the same as the $SYNCROOT if you are using a single VOB with Components 
+contained in a single directory and this will be offered as a default that you can accept 
+by hitting "Return".
+b) If you do not want new Components to be synchronised then create a dummy directory in 
+ClearCase (i.e. /vobs/SAMECS/sync_null) and enter this as the New Components location.  
+Likewise in RTC open the vobadm synchroniser workspace and ensure that the Flow Target for 
+the works space is a selected list of Components. (i.e. Open Flow Target Stream and then 
+edit to select the Components you want to synchronise).
+
+At this point the synchroniser will validate this entry to ensure that it is a valid RTC 
+Source Control share location by logging on to the Jazz Team Server (JTS) with the Jazz 
+Repository URI and password you have supplied in arguments 3 and 5.
+
+7. The parent directory location from where the synchroniser will run ($SCRIPT_LOCATION). 
+You will be offered a default that you can accept by hitting "Return". 
+
+ (i.e. /snapshot_views/SAMECS_admin _snapshot_view /vobs/SAMECS/jazz/rtc/imp/src
+ /rtc_base_clearcase_ workspace_synchronisation)
+
+8. The primary group for the ClearCase VOBs being synchronised ($GROUP). You will be 
+offered a default that you can accept by hitting "Return".
+
+Synchroniser instance creation and configuration
+------------------------------------------------
+Once you have entered the 8th argument the synchroniser will continue the setup and 
+configuration process by:
+
+a). Attempting to calculate he $VOBSROOT location (The part of the in the extended snapshot 
+view/VOB pathname up to and including where ../vobs/... occurs.
+
+  i.e. /snapshot_views/synchroniser_evaluation_snapshot_view/vobs)
+
+which it uses to check the existing triggers on the VOB to see if they could potentially 
+conflict with the running of the synchroniser
+
+For example, if it finds any triggers that use a "clearprompt", which may attempt to 
+interact with the synchroniser, it will display the trigger information and ask if you want 
+to proceed or terminate to allow you to take remedial action (i.e. remove the trigger or 
+set ClearCase environmental variables to stop the trigger interacting with the 
+synchroniser).
+
+Another option would be to add -nuser vobadm so that the trigger does not fire for the 
+synchroniser that is run by the vobadm user.
+
+b). Continuing its setup process and creating the log (.synclog), control and metrics files 
+and applying the ClearCase triggers, etc... that it will need at runtime.
+
+c). Attempting to populate the "components" file, which it does by checking the "scm 
+status" of the extended ClearCase snapshot view/VOB Repository Workspaces for Component 
+entries. At this point you will be prompted to either edit of accept what it has found. It 
+will be presented to you in the format:
+
+ <$WORKSPACE_UUID>*<$COMPONENT_UUID>*<Location relative to $SYNCROOT>
+
+and this format is fully explained in section "Control Files and synclog" 
+
+d). Finally, getting the synchroniser to list the "Flow Target" Stream (STREAM_UUID) for 
+the synchroniser Repository Workspace, which it does by listing the Streams.   
+
+Note: The easiest way the Stream_UUID is to open the Eclipse Team Artefacts view, select 
+the drop-down box for the RTC Project and under "Source Control" right-click on the Stream 
+for the synchroniser and select Open.  In the window that appears right-click the Stream 
+object (top left) and select "Copy URL" and paste the into a text editor
+
+  https://samecs.dev.com:9443/ccm/resource/itemOid/com.ibm.team.scm.Workspace
+  /_BJcY8KvzEeKE8M0emrpgkw
+
+The Steam UUID is the last entry on the line.
+
+This completes the synchroniser setup and configuration process and you will be given the 
+option to either start the synchroniser instance or Exit.
+
+  Do you want to start the synchroniser now? Y/N
+
+Notes: 
+i. The synchroniser stores the arguments entered in a file called "config" that is stored 
+in the logs/control files (LOGPATH) location and this file is sourced at runtime and is 
+reused if you rerun the synchroniser with the --CONFIG option:
+
+  ./rtc_clearcase_workspace_sync --CONFIG 
+
+ii. An additional 9th argument of --TEST will run the synchroniser in standalone test mode 
+and this is set a runtime as describe in the "Running a synchroniser instance" section 
+below.
+
+5.5.	Running a synchroniser instance
+========================================
+
+Daemonized script
+-----------------
+Once you have completed the "rtc_clearcase_workspace_sync --CONFIG" setup process, the 
+synchroniser will use the argument information to build a working synchroniser instance, 
+which can be run as daemon process that is controlled from the logs/control files 
+($LOGPATH) location with:
+
+  ./sync start
+  ./sync restart
+  ./sync stop
+
+Note: We have defined  "/snapshot_views/sync" to be the parent directory control files 
+location and it contains a sub-directory for each synchroniser instance, therefore, by way 
+of example:
+
+  /snapshot_views/sync/synchroniser_evaluation
+
+is the logs/control files location for the synchroniser_evaluation instance of the 
+synchroniser.
+
+Non-Daemonised script
+---------------------
+If you run the synchroniser with the following options it runs in a standalone mode and 
+sends its output to the screen as well as the log files. This is a useful option for 
+debugging and use during the infancy of a new synchroniser:
+
+  ./sync start --TEST
+  ./sync restart --TEST
+
+Updating an existing synchroniser instance
+------------------------------------------
+You can also rerun the initial  "rtc_clearcase_workspace_sync --CONFIG" for the 
+synchroniser instance by running:
+
+  ./sync -CONFIG
+
+This will take your initial responses for each of the 8 arguments and prompt you for 
+acceptance or editing, so this is how you would update a synchroniser instance. 
+
+5.6.	Concurrency of the Jazz SCM CLI
+=======================================
+By default Jazz SCM creates a ".jazz-scm" directory in the users (vobadm) home directory, 
+however, if home directories are shared across servers (the default for SAMECS) or if you 
+are running multiple synchroniser on one servers, again something that will happen on 
+SAMECS, then you need to have a per-user local copy of .jazz-scm and this is achieved by 
+the synchroniser by creating a local copy in the following location:
+
+  /tmp/<USER>/<SYNCHRONISER INSTANCE NAME>/.jazz-scm
+
+when copying the .jazz-scm directory structure if there are any references to existing 
+daemon (lscm) CLIs, which are stored in the .jazz-scm/daemons directory, they are deleted.
+
+5.7. Concurrency in general
+===========================
+Concurrency when synchronising applications is a big issue and the synchroniser has been 
+thoroughly tested in this area.  For instance, changing the contents of a file before it is 
+then renamed and moved to a new location, as part of the same operation (Change Set), has 
+been fully tested to ensure it get mirrored correctly between RTC Source Control and 
+ClearCase, as has, updating numerous objects in various sub-directories before then 
+renaming and moving the main parent directory. 
+
+
+Note: Git is not a version control system in the traditional sense and, as such, it relies 
+on file-system commit snapshots and not version deltas; therefore, for instance, the "git 
+mv" command does not actually rename or move a file it basically deletes and then adds a 
+new file so the synchroniser has top mirror this is the same fashion (delete and then add) 
+when synchronising Git with both RTC Source Control and ClearCase
+
+5.8.	Log/Control Files location
+==================================
+The Log/Control Files location is home to the synchroniser logs and a large number of 
+configuration/transient files used by the synchroniser. The following is a list of the most 
+important files:
+
+components
+----------
+The most important control file is the "components" file and the format for the contents of 
+the components file is:
+  <workspace_UUID>*<Component_UUID>*<Component Location>
+Example:
+  _bd3OcC0-EeClbY5-9MLdDw*_wsC0MAdyEeCHkf0O7NsKcg*samecs/releases*/-
+  _bd3OcC0-EeClbY5-9MLdDw*_wsbOsAdyEeCHkf0O7NsKcg*samecs/rpms
+  _bd3OcC0-EeClbY5-9MLdDw*_wtgz0AdyEeCHkf0O7NsKcg*samecs_web/webGuis/website/MajorWeb/*
+  _bd3OcC0-EeClbY5-9MLdDw*_wuS28AdyEeCHkf0O7NsKcg*samecs_web/webGuis/wingdings*/-
+Notes:
+i. The <Component Location> is the Components pathname relative to the synchroniser defined 
+synchronisation root ($SYNCROOT) location in the extended ClearCase snapshot view.
+
+Example:
+Full path to Component si:
+ /snapshot_views/synchroniser_release_5_snapshot_view/vobs/samecs_src/synchroniser
+
+$SYNCROOT:
+ /snapshot_views/synchroniser_release_5_snapshot_view/vobs/samecs_src/
+
+Component:
+ Portal
+
+Component Location:
+ src/synchroniser
+
+ii. An additional */- at the end of the line allows the sub-directories of the Component to 
+be loaded as Eclipse projects. This is the standard configuration when the synchroniser is 
+running and new Components are added.
+
+iii. The synchroniser creates a copy of the "components" file called "components_copy", 
+which can be .
+
+iv. in --CONFIG mode the synchroniser attempts to build this file, however, I would advise 
+you review and where necessary edit this file before starting the synchroniser for the 
+first time
+
+defaults
+--------
+The synchroniser creates a defaults file based on the "defaults" entries in SECTION 1 of 
+the synchroniser and these are the default values offered to the user when a new 
+synchroniser instance is created.
+
+ WINDOWS_DOMAIN="samecs.dev.com"
+ JAZZ_URI="https://samecs.dev.com:9443/ccm"
+ JAZZ_SCM_CONFIG="/tmp/vobadm/synchroniser_v4_0_2_testing"
+ ADMIN_EMAIL="support@samecs.dev.com"
+ RETURN_EMAIL_ADDRESS="support@samecs.dev.com"
+ EMAIL_RETURN_ADDRESS_FORMATTING=" -- -f "
+ CLASSIFICATION_HEADER=""
+ CLASSIFICATION_FOOTER=" "
+ EMAIL_CLASSIFICATION_SET="YES"
+ CONTROL_FILES_PARENT_DIRECTORY_LOCATION="/snapshot_views/sync"
+ SNAPSHOT_VIEW_VOB_LOCATION="/snapshot_views/synchroniser_evaluation_snapshot_view/vobs"
+ PASSWORD_FILE_LOCATION="/home/vobadm/vobadm_passwd.txt"
+ SYNCHRONISER_RUN_FROM_LOCATION="/snapshot_views/samecs_admin/vobs/samecs_src/synchroniser"
+ SCRIPT_NAME="rtc_clearcase_workspace_sync"
+ EMAIL_USER="support@samecs.dev.com"
+ RUNNING_AS_USER="vobadm"
+ PRIMARY_GROUP="ngcc_u"
+ SCMTOOLS_DEFAULT="/opt/IBM/TeamConcert/scmtools/eclipse"	
+ SCMTOOLS_ALTERNATIVE="/opt/IBM/TeamConcertBuild/scmtools/eclipse"
+
+config
+------
+This file, amongst other things, contains a copy of the 8 input argument used by the 
+synchroniser and if the config exists these arguments are sourced and passed back to the 
+synchroniser for reuse when running the following synchroniser configuration commands:
+
+  ./sync --CONFIG
+  ./rtc_clearcase_workspace_sync -CONFIG
+
+An example of a config file is shown below:
+
+ LOGPATH="/snapshot_views/sync/synchroniser_v4_0_2_testing*\\\\samecs.dev.co\\snapshot_views
+ \\sync\\synchroniser_v4_0_2_testing"
+ SYNCROOT="/snapshot_views/rtc_clearcase_workspace_synchroniser_rtc_v4_0_2_testing  
+ _snapshot_view/vobs/synchroniser_evaluation"
+ REPHOST="https://samecs.dev.com:9443/ccm"
+ PASSWDFILE="/home/vobadm/vobadm_passwd.txt"
+ NEW_COMPONENTS_LOCATION="/snapshot_views/rtc_clearcase_workspace
+ _synchroniser_rtc_v4_0_2_testing_snapshot_view/vobs/synchroniser_evaluation"
+ SCRIPT_LOCATION="/releases/rtc"
+ GROUP="ccadm_u"
+ EMAIL="support@samecs.dev.com -- -f support@samecs.dev.com"
+ RETURN_EMAIL_ADDRESS="support@samecs.dev.com"
+ EMAIL_RETURN_ADDRESS_FORMATTING=" -- -f "
+ CLASSIFICATION_HEADER=" "
+ CLASSIFICATION_FOOTER=" "
+ EMAIL_CLASSIFICATION_SET="YES"
+ EMAIL_USER="support@samecs.dev.com"
+ STREAM_UUID="_AfRT4KEZEeKa_tNjWqU9zA"
+ SCMTOOLS="/opt/IBM/TeamConcert/scmtools/eclipse"
+ STARTING="NO"
+ SYNC_BRANCH="rtc_clearcase_workspace_synchroniser_v4.0.2"
+ RUNNING_AS_USER="vobadm"
+
+metrics.txt (One at the Component level and one at the synchroniser level)
+--------------------------------------------------------------------------
+These, comma delimited, files store metrics information of the synchronisers activities in 
+the following format:
+ Date&Time,SynchroniserInstance,Component,Direction,Command,Action,NumberOfFiles,Data,TimeTaken
+ 23_06_11@06_53_00:,samecs,Access_products_java,ClearCase->RTC,"scm -u y -a n 
+ checkin",---c,28,0,10
+ 23_06_11@15_01_36:,samecs,Samecs_elements_cpp,ClearCase->RTC,"scm -u y -a n 
+ checkin",--a-,2,4503,12
+ 23_06_11@15_28_28:,samecs,Samecs_elements_cpp,ClearCase->RTC,"scm -u y -a n 
+ checkin",---c,3,1774,11
+ 23_06_11@15_33_26:,samecs,Samecs_elements_lib,ClearCase->RTC,"scm -u y -a n 
+ checkin",-dac,30,75266,14
+ 23_06_11@15_42_28:,samecs,Access_products_rpms,ClearCase->RTC,"scm -u y -a n 
+ checkin",--ac,19,6856920,13
+
+Heading	Description
+ Date&Time:		Date (DD_MM_YY) and time (HH_MM_SS) of the activity.
+ Synchroniser Instance:	Name of the synchroniser instance
+ Component :		The name of the Component being processed
+ Direction:	        Either "RTC to ClearCase" or "ClearCase to RTC"
+ Command:	        Short description of the command (i.e. scm checkin)
+ Action:                A 4 character string highlighting what the command did:
+                            Renamed/Moved	= m---
+                            Deleted		= -d--
+                            Added		= --a-
+                            Changed (updated)	= ---c
+ NumberOfFiles	        The number of files being processed.
+ Data:	                The amount of data involved in bytes
+ Time Taken:	        The time taken for the activity in seconds.
+
+refactor.sh & refactor.pl
+-------------------------
+The synchroniser installs a post operational ClearCase VOB trigger on the hidden "lnname" 
+ClearCase command and this allows the synchroniser to track ClearCase refactoring activity. 
+To implement this, the synchroniser creates two scripts: refactor.sh (UNIX/Linux) and 
+refactor.pl (Windows) and the one that runs is dependent upon the end-user environment 
+(UNIX/Linux or Windows). The data collected by the scripts allows the synchroniser to 
+mirror ClearCase refactoring (Rename and Move) activity in RTC Source Control.
+
+Notes: 
+i.Execute permissions must exist on the scripts for the owner, group and others:
+ -rwxr-xr-x  1 vobadm samecs     1783 Apr 23 12:06 refactor.pl
+ -rwxr-xr-x  1 vobadm samecs      689 Apr 23 12:06 refactor.sh
+ii. The post operational trigger uses the following naming convention:
+  refactor_<STREAM_UUID>
+
+This allows multiple synchroniser to run against the same VOB but on different ClearCase 
+Branches/RTC Source Control Streams.
+
+synclog
+-------
+Any meaningful transactions (i.e. cleartool and scm commands that create change) are logged 
+in the synchroniser log, which is called "synclog". You can also turn on a higher level of 
+logging by placing a file named ".full_logging" in the synchroniser instances control file 
+location.  
+
+An example of a log output is give below:
+ *********************************************************************
+ 03_08_11@10_33_24: Running "scm -u y -a n accept -C rc5 test"
+ 03_08_11@10_33_33: (See output below:)
+ Repository: https://samecs.dev.com:9443/ccm/
+ Workspace: (_8IojcKe8EeCbbt4zvI36Cg) "vobadm_synchroniser_development_workspace"
+ Component: (_Sv9Y0L26EeCYhu87w_ih8w) "rc5 test"
+ Change sets:
+ (_4fY9Ib27EeCYhu87w_ih8w)  ---$ SAMECS <No comment>
+ Changes:
+ ---c- /rc5 test/level 1 test.sh
+ ---c- /rc5 test/Level 1/test.sh
+ **********************************************************************
+ 03_08_11@10_33_33: The following files are hijacked (See output below):
+ level1 test.sh
+ ./Level 1/test.sh
+ **********************************************************************
+  Running: cleartool co -usehijack | cleartool ci against the above
+ **********************************************************************
+ 03_08_11@10_33_33: synchroniser metrics generated
+ 03_08_11@10_33_33:,synchroniser_development,rc5 test,RTC->ClearCase,"cleartool co 
+ -usehijack & ci",---c,2,13652,1
+ ********************************************************************** 
+
+5.8.1.	Other control files with a description:
+===============================================
+
+.classpath.ignore & .build.xml.ignore
+-------------------------------------
+When created in the control files area it allows different ".classpath" files to exist in 
+both the ClearCase and RTC source control environments. This control file can be set at the 
+synchroniser or individual Component levels.
+
+.clearcase.ignore
+-----------------
+When created and populated any files named in the ".clearcase.ignore" file are ignored by 
+the synchroniser. This control file can be set at the synchroniser or individual Component 
+levels. Note: This mirrors the functionality of the out-of-the-box .jazzignore used by RTC 
+Source Control.
+
+.clearcase_to_rtc_sync.ignore
+-----------------------------
+When created, it stops ClearCase updates being sent to RTC source control. This control 
+file can be set at the synchroniser or individual Component levels.
+
+.cli_version
+------------
+Stores the current version of the Jazz SCM CLI and is used by the synchroniser to allow for 
+variance interface. 
+
+.empty
+------
+Identifies the data status of the Component:
+* "NO" indicates that it contains data
+* "YES" indicates that the Component is empty
+
+.full_logging
+-------------
+When created in the control files area it turns on a high-level of logging (i.e. list all 
+checkout and checkins rather than a summary). This control file can be set at the 
+synchroniser or individual Component levels.
+
+.get_symlinks
+-------------
+RTC Source Control does not fully support symbolic linking; therefore, when created, the 
+.get_symlinks control file lists the ClearCase symbolic links in the VOB sub-directory 
+Component that will not be reflected in RTC Source Control. For each Component the output 
+is sent to the file:
+
+<$LOGPATH>/$COMPONENT_UUID/.symlinks
+
+Note: You should not leave the ".get_symlink" flag turned on permanently as this will 
+affect the performance on the synchroniser.
+
+.git_sync
+---------
+If the file exists the synchroniser pushes RTC Source Control and ClearCase changes to a 
+central Git Hub repository (Component). This control file can be set at the synchroniser or 
+individual Component levels.
+
+Note: A number of other steps are required to activate Git synchronisation and these are 
+detailed in  Git synchronisation
+
+.hostname
+---------
+This control file contains the "hostname" of the server for the synchroniser instance and 
+ensures that
+* the "./sync stop" and ./sync start" are run on the correct server host.
+* a second instance is not started when one is already running.
+
+.last_run
+---------
+A time-stamped control file that is updated by the synchroniser before the processing of 
+each Component begins, which can be used to see if a synchroniser has stopped running.  On 
+SAMECS we run an hourly cronjob of samecs.dev.com, which emails SAMECS  Support if a 
+synchroniser instance has stopped working.
+
+.lscm_override
+--------------
+If the Components being synchroniser exist at different ClearCase VOB sub-directory levels 
+then the synchroniser defaults to using individual "scm" commands rather than the standard 
+permanently running "lscm" daemon command. However, you can continue to run the "lscm" 
+daemon as long as the Component pathname do not overlap; therefore, the ".lscm_override" 
+control file was created to allows usage of the "lscm" command in such situations. 
+
+.no_component_rename
+--------------------
+By default a Component appears in the components files as a Component that contains Eclipse 
+project sub-directories (i.e. has */-" ending to the line) and, as such, the Component 
+named sub-directory in ClearCase and the RTC Source Control Component are linked; 
+therefore, if one is renamed, say in ClearCase, then it will get renamed in RTC Source 
+Control.  There may be occasions when you want the Component to be renamed in one tool but 
+not in the other so creating the ".no_component_rename" control file, which can be set at 
+the synchroniser or individual Component levels, allows this to happen.
+
+.no_git_pull
+-----------
+When this file exists in a control files area, it will stop the synchroniser running the 
+"git pull" command that pulls changes from the "Git Hub" repository into the RTC Source 
+Control and ClearCase linked Component. This control file can be set at the synchroniser or 
+individual Component levels.
+
+.no_git_tag
+-----------
+When this file is exists in a control files area, it will stop the synchroniser running the 
+"git tag" command that mirrors RTC Source Control baseline in the equivalent "Git Hub" 
+linked repository. This control file can be set at the synchroniser or individual Component 
+levels.
+
+.no_label
+---------
+By default RTC Source Control created Baselines generate a ClearCase mklbtype followed by a 
+silent mklabel of the equivalent files in ClearCase, however, if the ".no_label" control 
+file, which can be set at the Instance or Component level, exists the labelling activity in 
+ClearCase does not take place.
+
+.poc
+----
+The ".poc" file is designed to hold the email addresses of the RTC Source Control/ClearCase 
+project related Points Of Contact (POCs).  The list should contain members of the project 
+hierarchy that should be emailed if the synchroniser experiences any processing issues. 
+This control file can be set at the synchroniser or individual Component levels.
+
+.rtc_to_clearcase_sync.ignore
+-----------------------------
+When this control exists it stops RTC Source Control events being sent to ClearCase. This 
+control file can be set at the synchroniser or individual Components level.
+
+Note: This means that the RTC Source Control Change Sets will "backup" in the synchroniser 
+Repository Workspace; therefore, you should monitory the synchroniser instance closely if  
+this control file is removed as it could "open the floodgates" with changes bound for 
+ClearCase, which may take considerable time to process.
+
+.script_run_stop
+This control file contains either the word "run" or "stop" and is populated by the ./sync 
+start|stop|restart script options, where the "./sync stop" option changes the contents to 
+"stop" and causes the synchroniser to terminate after it has processed its current 
+Component.
+
+.sync_branch
+------------
+Stores the name of the ClearCase branch being used by the synchroniser instance.
+
+.stream_workspace_components_differ
+-----------------------------------
+There are occasions when the synchroniser is only required to synchroniser certain 
+Components in a Stream. If this is the case then you need to create 
+".stream_workspace_components_differ" in the synchroniser instances control files area 
+($LOGPATH)
+
+.version
+--------
+This control file stores the version number of the synchroniser that is currently running. 
+It sources its information from $SYNC_VERSION variable which is defined at the beginning of 
+the synchroniser shell script.
+
+5.8.2. Transient files in the control file area
+===============================================
+The synchroniser also creates a large number of transient files that are generated from the 
+"cleartool" and "scm" command outputs and these are used for logging and error trapping 
+purposes. 
+
+6. Synchronising RTC Source Control and ClearCase changes with a Git Hub
+========================================================================
+With effect v5 of the synchroniser RTC Source Control and ClearCase changes can be 
+synchronised with a central Git Hub repository, however, to activate the "git sync" part of 
+the synchroniser there are some administration level tasks that need completing first.
+
+a). Stop the synchroniser instance:
+
+ $ cd /snapshot_views/sync/<synchroniser instance>
+ $ ./sync stop
+
+b). Change directory to the extended ClearCase snapshot view/VOB/Component Linux operating 
+system location:
+
+For this example the snapshot view location of the "synchroniser_evaluation_ snapshot_view" 
+is:
+
+ /snapshot_views/rtc_clearcase_workspace_synchroniser_v4.0.1_snapshot_view
+
+The extended snapshot view/VOB location for the synchroniser_evaluation VOB extends this 
+path to:
+
+ /snapshot_views/rtc_clearcase_workspace_synchroniser_v4.0.1_snapshot_vie 
+ /vobs/synchroniser_evaluation
+
+And the Component is "Volcano". In this example the Component is located in the root of the 
+VOB giving a final extended snapshot view/VOB/Component pathname of:
+
+ /snapshot_views/rtc_clearcase_workspace_synchroniser_v4.0.1_snapshot_view
+ /vobs/synchroniser_evaluation/Volcano/
+
+So cd to the extended ClearCase snapshot view/VOB/Component location, which should contain 
+the .jazz5/ RTC Source Control "metadata" directory.
+
+ cd /snapshot_views/rtc_clearcase_workspace_synchroniser_  
+ v4.0.1_snapshot_view/vobs/synchroniser_evaluation/Volcano/
+
+c). If one does not exist in this location create a .jazzignore file so that we can ignore 
+the Git control files
+
+ $ touch .jazzignore
+
+and populate either the existing or new file as follows:
+
+ $ echo .git/ >> .jazzignore
+ $ echo .gitignore >> .jazzignore
+ $ cat .jazzignore
+ .git/
+ .gitignore
+
+d). If one does not exist in this location create a .gitignore file so that Git can ignore 
+the Jazz control files.
+
+ $ touch .gitignore
+
+and populate either the existing or new file as follows:
+
+ $ echo .jazz5/ >> .gitignore 
+ $ echo .metadata/ >> .gitignore
+ $ echo clientdb.xml >> .gitignore
+ $ echo .jazzShed/ >> .gitignore
+ $ echo .jazzignore >> .gitignore
+ $ cat .gitignore
+ .jazz5/
+ .metadata/
+ clientdb.xml
+ .jazzShed/
+ .jazzignore
+
+e). In the same extended snapshot view/VOB/Component location initialise (create) a local 
+git repository by running:
+
+ $ git init
+ Initialized empty Git repository  
+ in /snapshot_views/rtc_clearcase_workspace_synchroniser_v4.0.1_snapshot_view/vobs/
+ synchroniser_evaluation/Volcano/.git
+
+f). Start tracking all the objects in the "Volcano" directory by staging them ready to add 
+to local git repository you have just created by running:
+
+ $ git add -- all
+
+Note: The ".gitignore" file tells git to ignore the Jazz related control files
+
+g). Commit the staged files into the local repository by running:
+
+ $ git commit -m "Initial Commit"
+ [master (root-commit) 23ff378] Initial Commit
+ 6 files changed, 79 insertions(+)
+ create mode 100644 .gitignore
+ create mode 100755 Volcano/.classpath
+ create mode 100755 Volcano/.project
+ create mode 100755 Volcano/.settings/org.eclipse.jdt.core.prefs
+ create mode 100755 Volcano/src/VolcanoApplication.java
+ create mode 100755 Volcano/src/VolcanoRobot.java
+ $
+
+h). If you have not already created a Git Project and Repository that you are going to link 
+to the RTC Source Control Component/ClearCase sub-directory then logon to the Git Hub 
+Enterprise management tool, create a Project and a Repository that you are going to link to 
+the RTC Source Control Component/ClearCase VOB sub-directory, which in this example is 
+"Volcano". You now need to add the remote Repository using:
+
+ $ git remote add Volcano ssh://git@samecs.dev.com:7999/JSGS/volcano.git
+
+Notes: You can check the remotes with:
+
+ $ git remote -v
+ Volcano ssh://git@samecs.dev.com:7999/JSGS/volcano.git (fetch)
+ Volcano ssh://git@samecs.dev.com:7999/JSGS/volcano.git (push)
+
+Component names can be long so if you wanted to shorted the remote repository name to, say, 
+"vol" rather than "Volcano" you can do this by creating an "..git_remote" file in the 
+control files area and populating the file with the shortened name.
+
+ cd /snapshot_views/sync/synchroniser_v4.0.1_testing
+
+Cat the components file and get the Component UUID location, which is the entry after the 
+first *:
+
+ cat component
+ ....
+ _RGlAcGrLEeKpwdFSiAVPNQ*_v7TGsHnFEeKpwdFSiAVPNQ*Volcano*/-
+ ....
+
+cd to the Component UUID location:
+
+ cd *_v7TGsHnFEeKpwdFSiAVPNQ
+
+Touch the .git_remote file and populate with the shortened remote repository name:
+
+ touch .git_remote
+ echo "vol" > .git_remote
+
+If the remote already exists you can remove this with:
+
+ $ git rm Volcano
+
+You can then add the alias to identify the remote with:
+
+ $ git remote add vol ssh://git@samecs.dev.com:7999/JSGS/volcano.git
+
+i). Push the data committed to the local repository to the remote Git Hub repository
+
+ $ git push Volcano master
+ Counting objects: 11, done.
+ Delta compression using up to 4 threads.
+ Compressing objects: 100% (11/11), done.
+ Writing objects: 100% (11/11), 1.68 KiB, done.
+ Total 11 (delta 0), reused 0 (delta 0)
+ To ssh://git@samecs.dev.com:7999/JSGS/volcano.git
+ * [new branch]      master -> master
+ $
+
+Notes: 
+1. If there are issues with the RSA key they will be highlighted at this point and can be 
+resolved at this time as well.
+
+ The authenticity of host 'samecs.dev.com (192.168.0.10)' can't be established.
+ RSA key fingerprint is 01:3c:6c:f6:9e:af:f1:34:38:20:2a:de:b6:79:6b:ca.
+ Are you sure you want to continue connecting (yes/no)? yes
+ Warning: Permanently added 'samecs.dev.com,192.168.0.10(RSA) to the list of known hosts.
+ Counting objects: 11, done.
+ Delta compression using up to 4 threads.
+ Compressing objects: 100% (11/11), done.
+ Writing objects: 100% (11/11), 1.68 KiB, done.
+ Total 11 (delta 0), reused 0 (delta 0)
+ To ssh://git@samecs.dev.com:7999/JSGS/volcano.git
+ * [new branch]      master -> master
+ $
+
+2. If you see the following error:
+
+ To ssh://git@samecs.dev.com:7999/JSGS/dmoz.git
+ ! [rejected]        master -> master (non-fast-forward)
+ error: failed to push some refs to 'ssh://git@samecs.dev.com:7999/JSGS/dmoz.git'
+ hint: Updates were rejected because the tip of your current branch is behind
+ hint: its remote counterpart. Merge the remote changes (e.g. 'git pull')
+ hint: before pushing again.
+ hint: See the 'Note about fast-forwards' in 'git push --help' for details.
+
+Try the following which will force the changes to be pushed:
+
+ $ git push -f Volcano master
+
+j). Check the status of the workspace (i.e. the extended ClearCase snapshot view/VOB
+/Component location) by running:
+
+ $ git status
+ # On branch master
+ nothing to commit (working directory clean)
+
+k). Getting the RTC ClearCase workspace synchroniser to push updates to Git. Cd to the 
+control file area, which will be a sub-directory under:
+
+ /snapshot_views/sync
+
+So for this example the directory is:
+
+ /snapshot_views/sync/synchroniser_v4.0.1_testing
+
+cat the components file to get the Component UUID, in this case for the Volcano Component:
+
+ $ cat components
+ _RGlAcGrLEeKpwdFSiAVPNQ*_f5qPsGrKEeKpwdFSiAVPNQ*RTC_Analytics*/-
+ _RGlAcGrLEeKpwdFSiAVPNQ*_a0UowXnMEeKpwdFSiAVPNQ*String^Checker^renamed*/-
+ _RGlAcGrLEeKpwdFSiAVPNQ*_C8yy8XnMEeKpwdFSiAVPNQ*Weather*/-
+ _RGlAcGrLEeKpwdFSiAVPNQ*_v7TGsHnFEeKpwdFSiAVPNQ*Volcano*/-
+
+cd to the Component UUID location, which is the second UUID in the Components file directly 
+before the Component name:
+
+ $ cd _v7TGsHnFEeKpwdFSiAVPNQ/
+
+Create the .git_sync file
+
+ $ touch .git_sync
+
+Note: If the .git_sync file is left blank then "master" will be assumed.
+
+l). Start the synchroniser by cd ing back to the control files area:
+
+ $ cd ..
+
+Start the synchroniser:
+
+ ./sync start
+
+Note: If you want to observer the output start the synchroniser as follows:
+
+ ./sync start --TEST
+
+6.1. Pulling changes from the Git Hub Repository
+================================================
+By default the synchroniser is configured to pull any changes from the Git Hub Repository 
+into RTC Source Control and ClearCase, however, this is not always required and can be 
+stopped by adding the control file:
+
+ .no_git_pull
+
+to the control files area. This control file can be set at the synchroniser or individual 
+Component levels.
+
+6.2. RTC Source Control Component Baseline mirroring to a Git Hub Repository
+============================================================================
+When an RTC Source Control baseline is accepted by the synchroniser, by default, it creates 
+a ClearCase label type based on the Baseline name and then applies it to all the equivalent 
+Component sub-directory files in ClearCase. In addition, if the Component is being 
+synchronised with a Git Hub repository then an equivalent "git tag" will be applied to all 
+the equivalent Component files in the Git Hub repository.
+
+Note: Setting the .no_git_label control file stops the "git tag" operation taking place and 
+setting the  ".no_label" control file stops both the "ClearCase label"  and "git tag" 
+operations.
+
+7. WARNING: Permissions are key dont manually change things in the synchroniser workspace
+=========================================================================================
+Once you have created the jazz scm share you are advised to manually edit anything in that 
+is shown as the black-box synchroniser in the diagram on the next page.  For instance if 
+you manually check out and then check in a file into the VOB from the synchroniser 
+ClearCase snapshot view it will change the files permissions in such a way that the local 
+workspace (sandbox) see this as a change and will create a circular update.
+ 
+To reiterate the synchroniser controls this behaviour with the permissions function, where 
+basically the permissions of a file are captured before it is updated and reset back to 
+exactly the same permissions after the update.
+
+Permissions are key to the success of the synchroniser, which ensures files can be written 
+to when they are created or updated in the local workspace (sandbox)/snapshot view 
+location.  
+
+8. Maintenance of the synchroniser and what to do when it goes wrong
+====================================================================
+
+a) The synchroniser is running but is not processing anything.
+--------------------------------------------------------------
+Stop the synchroniser "./sync stop" if that does not work run "ps -ef | grep scmtools" and 
+kill the ones that are still running.
+
+Note: If there is an outgoing Change Set with not comment stop the synchroniser cd to the 
+extended snapshot view VOB location and set the Change Set comment with:
+
+ scm -u y -a n changeset comment <Change Set UUID> "<suitable comment>"
+ scm deliver <Change Set UUID>
+
+b)The synchroniser reports that the "Local file system is out of sync." -- 
+--------------------------------------------------------------------------
+*** Run scm load -force <$WORKSPACE_UUID>
+-----------------------------------------
+
+As the output below highlights in the last line you need to run and scm load -force 
+<WORKSPACE_UUID> < COMPONENT_UUID>
+
+ vobadm@jade$ scm status -v -w
+ Local filesystem is consistent.
+ Password (vobadm @ https://samecs.dev.com:9443/ccm/):            
+ Workspace: (0918) "vobadm Synchroniser Release 5 Workspace" <-> (0919) "Synchroniser 
+ Release 5"  
+ (vobadm @  https://samecs.dev.com:9443/ccm/)
+  Component: (0920) "Synchroniser" <-> (0919) "Synchroniser Release 5"
+    Baseline: (0921) 70 "POST_CLEARCASE_IMPORT_RELEASE_4"
+    Incoming:
+      Change sets:
+        (0935)  ---$ xxxx xxxx 212072 "Modification logic needs to apply when editing saved 
+        draft modification" - <No comment>
+        (0922)  ---$ xxxx xxxx 212366 "Fix wrapping of text for long report titles in 
+ Editor LaunchPad  widget" - <No comment>
+ ...
+ ...
+ Some components in (0918) "vobadm Syncroniser Release 5 Workspace" are out of sync.
+    (0920) "Synchroniser"
+ Local filesystem is out of sync. Run 'scm load' with --force option to reload the 
+ workspace.
+
+Which can be resolved by running "scm load -force <WORKSPACE_UUID>" or for an individual 
+Component with: "scm load -force <WORKSPACE_UUID> <COMPONENT_UUID>"
+ vobadm@jade$ scm load --force 0918 0920
+ Password (vobadm @ https://samecs.dev.com:9443/ccm/):            
+ Downloading /xxxx/.jazzignore  (772 B)
+ Downloading /xxx-source.jar  (2.0 KB)
+ ...
+Rechecking the status now shows that the synchroniser workspace in now back in sync ready 
+for being used by the synchroniser
+ vobadm@jade$ scm status -v -w
+ Local filesystem is consistent.
+ Password (vobadm @ https://samecs.dev.com:9443/ccm/):            
+ Workspace: (0918) "vobadm Synchroniser Release 5 Workspace" <-> (0919) "Synchroniser 
+ Release 5" 
+ (vobadm @  https://samecs.dev.com:9443/ccm/)
+  Component: (0920) "Synchroniser" <-> (0919) "Synchroniser Release 5"
+    Baseline: (0921) 70 "POST_CLEARCASE_IMPORT_RELEASE_4"
+    Incoming:
+      Change sets:
+        (0935)  ---$ xxxx xxxx 212072 "Modification logic needs to apply when editing 
+         saved draft modification" - <No comment>
+        (0922)  ---$ xxxx xxxx 212366 "Fix wrapping of text for long report titles in
+ ....
+
+c) How to do a manual check of a synchroniser instance
+------------------------------------------------------
+First cd to the synchronisation root directory e.g:
+ /snapshot_views/rtc_clearcase_workspace_development_snapshot_view
+ /vobs/synchroniser_evaluation
+
+or if the Component only contains Eclipse project sub-directories (i.e. the line in the 
+$LOGPATH/components file ends in a /*-) the Component directory e.g:
+
+ /snapshot_views/rtc_clearcase_workspace_development_snapshot_vie
+ /vobs/synchroniser_evaluation/Volcano
+
+Checking RTC by running:
+
+ scm -u y -a n status -v -w
+
+What you are looking for here is the fact that the local workspace is consistent:
+ Local filesystem is consistent.
+ Workspace: (_N_WRkJN2EeG78qH6aTWnyQ) "vobadm Synchroniser Release 5 synchroniser 
+ workspace" <->   
+ (_FgOZwG3SEeGlA-_5-5kCuQ) "Synchroniser Release 5"  (vobadm @ https://samecs.dev.com:9443
+ /ccm/)
+ Component: (_v7lbIBXCEeGWk9R6Iu9Sbg) "Synchroniser" <-> (_FgOZwG3SEeGlA-_5-5kCuQ) 
+ "Synchroniser Release 5"
+ Baseline: (_bljPcpOgEeG78qH6aTWnyQ) 33 "POST_SYNCHRONISER_REL_4"
+Note: The synchroniser uses the following commands to check for updates in the ClearCase 
+snapshot view:
+
+ # Update the View with what has changed in the VOB
+ cleartool update <Extended snapshot view/VOB/sub-directory Component location>
+
+ # Check for any hijacked files, which will occur when RTC updates are sent to ClearCase
+ cleartool ls -r -visible . | grep -w hijacked
+
+ # Check for any new files added in RTC bound for ClearCase
+
+ cleartool ls -r -visible . | grep -v Rule:
+
+These commands can be used to check the status of the contents of the snapshot view 
+workspace that connects RTC source control and ClearCase
+
+d) The synchroniser has incorrectly delivered a Change Set
+----------------------------------------------------------
+If the synchroniser has incorrectly delivered changes fro ClearCase to RTC then, as a RTC 
+Project team member open the Jazz SCM Pending Changes view accept the incoming Change Set 
+then open the Component History in the Pending Changes View and reverse the Change Set you 
+have just received.  This will create a patch that should be merged with the workspace, 
+which will reverse the Changes and this should then be delivered to the rest of the 
+Projects Team members.
+
+e) Using the RTC Eclipse client GUI to resolve issues in local (sandbox) workspace
+-----------------------------------------------------------------------------------
+It is perfectly acceptable to stop the synchroniser and start the RTC Eclipse client GUI as 
+vobadm to resolve any conflict issues:
+
+	/opt/IBM/TeamConcert/Eclipse
+
+Note: If the synchroniser has been running the "lscm" daemonised CLI it will continue to 
+run once you have stopped the synchroniser. To rectify this run:
+
+ps -ef | grep scm
+
+vobadm     418     1  0 07:11 pts/1    00:00:08 /opt/IBM/TeamConcert/scmtools/eclipse/scm 
+--config /home/vobadm/.jazz-scm daemon start --connection-timeout 120000 --inactive-timeout 
+7200000
+
+and kill the process#
+
+f) A synchroniser instance will not start but no process is running to kill
+---------------------------------------------------------------------------
+The issue was resolved when I removed the /tmp/vobadm/<synchroniser name>/.jazz-scm instance
+
</pre>

WikiPage Home modified by Geoff Bush

Geoff Bush — Mon, 18 Mar 2013 22:27:21 -0000

The “RTC ClearCase workspace synchroniser“ (synchroniser) is a Linux/UNIX based tactical solution, which allows base ClearCase sub-directory components/products to be bi-directionally synchronised with RTC source control Components in real-time.