contrib/client-side/svn_load_dirs/svn_load_dirs.README

   1 Introduction
   2 ============
   3
   4 This Perl script is designed to load a number of directories into
   5 Subversion.  This is useful if you have a number of .zip's or
   6 tar.{Z,gz,bz2}'s for a particular package and want to load them into
   7 Subversion.
   8
   9 Command Line Options
  10 ====================
  11
  12 Run the script with no command line arguments to see all the command
  13 line options it takes.
  14
  15 When Not To Use This Script
  16 ===========================
  17
  18 This script assumes that these packages were not previously in a
  19 source control system, in particular CVS, because then you would use
  20 another script to migrate the repository over, and in CVS' case, you
  21 would use cvs2svn.  This script will properly tag each release in the
  22 tags directory if you use the -t command line option.
  23
  24 Automatically Setting Properties On New Files & Directories
  25 ===========================================================
  26
  27 The script also accepts a separate configuration file for applying
  28 properties to specific files and directories matching a regular
  29 expression that are *added* to the repository.  This script will not
  30 modify properties of already existing files or directories in the
  31 repository.  This configuration file is specified to svn_load_dirs.pl
  32 using the -p command line option.  The format of the file is either
  33 two or four columns:
  34
  35 regular_expression  control  property_name  property_value
  36
  37    The `regular_expression' is a Perl style regular expression.  It is
  38    matched in a case-insensitive against filenames.
  39
  40    The `control' must either be set to `break' or `cont'.  It is used
  41    to tell svn_load_dirs.pl if the following lines in the
  42    configuration file should be examined for a match or if all
  43    matching should stop.  If `control' is set to `break', then no more
  44    lines from the configuration file will be matched.  If `control' is
  45    set to `cont', which is short for continue, then more comparisons
  46    will be made.  Multiple properties can be set for one file or
  47    directory this way.
  48
  49    The last two, `property_name' and `property_value' are optional and
  50    are applied to matching files and directories.
  51
  52 If you have whitespace in any of the `regular_expression',
  53 `property_name' or `property_value' columns, you must surround the
  54 value with either a single or double quote.  You can protect single or
  55 double quotes with a \ character.  The \ character is removed by this
  56 script *only* for whitespace and quote characters, so you do not need
  57 to protect any other characters, beyond what you would normally
  58 protect for the regular expression.
  59
  60 This sample configuration file was used to load on a Unix box a number
  61 of Zip files containing Windows files with CRLF end of lines.
  62
  63    \.doc$              break   svn:mime-type   application/msword
  64    \.ds(p|w)$          break   svn:eol-style   CRLF
  65    \.ilk$              break   svn:eol-style   CRLF
  66    \.ncb$              break   svn:eol-style   CRLF
  67    \.opt$              break   svn:eol-style   CRLF
  68    \.exe$              break   svn:mime-type   application/octet-stream
  69    dos2unix-eol\.sh$   break
  70    .*                  break   svn:eol-style   native
  71
  72 In this example, all the files should be converted to the native end
  73 of line style, which the last line of the configuration handles.  The
  74 exception is dos2unix-eol.sh, which contains embedded CR's used to
  75 find and replace Windows CRLF end of line characters with Unix's LF
  76 characters.  Since svn and svn_load_dirs.pl converts all CR, CRLF and
  77 LF's to the native end of line style when `svn:eol-style' is set to
  78 `native', this file should be left untouched.  Hence, the `break' with
  79 no property settings.
  80
  81 The Windows Visual C++ and Visual Studio files (*.dsp, *.dsw, etc.)
  82 should retain their CRLF line endings on any operating system and any
  83 *.doc files are always treated as binary files, hence the
  84 `svn:mime-type' setting of `application/msword'.
  85
  86 Example Import
  87 ==============
  88
  89 An example import follows:
  90
  91 Steps:
  92
  93 1) Unpack your .tar.{Z,gz,bz2}'s or .zips into a directory that is not
  94    in a Subversion repository.
  95
  96    Example:
  97
  98    I'll use an example from my Orca distribution:
  99
 100       % cd /tmp
 101       % zcat orca-0.18.tar.gz | tar xf -
 102       % zcat orca-0.27b2.tar.gz | tar xf -
 103
 104 2) Decide on the directory structure you want to use to contain the
 105    project you are loading.
 106
 107    There are three main directory structures you can use.  If you have
 108    a single project, then use the structure Subversion uses for
 109    itself, that is
 110
 111       /branches
 112       /tags
 113       /trunk
 114
 115    and load the project into /trunk and the tags into the tags
 116    directory.
 117
 118    If you have more than one project and you want to treat each
 119    project separately, then use one of the following structures:
 120
 121       /branches
 122       /tags
 123       /tags/project1
 124       /tags/project2
 125       /tags/project3
 126       /trunk
 127       /trunk/project1
 128       /trunk/project2
 129       /trunk/project3
 130
 131    or
 132
 133       /project1/branches
 134       /project1/tags
 135       /project1/trunk
 136       /project2/branches
 137       /project2/tags
 138       /project2/trunk
 139
 140    Example:
 141
 142    To load Orca using the second directory structure into the
 143    subversion repository rooted at http://svn.orcaware.com:8000/repos
 144
 145       % cd /tmp
 146       % svn co http://svn.orcaware.com:8000/repos
 147       % cd repos
 148       % mkdir tags tags/orca trunk trunk/orca
 149       % svn add tags trunk
 150       % svn commit -m 'Create initial directory tree structure for projects.'
 151
 152    This script will create any subdirectories required to import your
 153    directories into the repository, so these steps may not be required.
 154
 155 3) Decide on the URL to use to access the subversion repository with
 156    this script and the relative directory paths to the directories to
 157    import your project into and to place the tags into.
 158
 159    The usage of the script is
 160
 161    ./svn_load_dirs.pl [-t tag_dir] svn_url import_dir dir_v1 [dir_v2 [..]]
 162
 163    The import_dir and tag_dir command line options are directory paths
 164    relative to svn_url and tell the script where to load your project
 165    and optionally the tags.  Both import_dir and tag_dir cannot
 166    contain any ..'s and so svn_url must contain both import_dir and
 167    tag_dir.
 168
 169    This script supports importing your directories into subdirectories
 170    of the root of the subversion repository.
 171
 172    Example:
 173
 174    In the previous step, if you wanted to load a project named orca
 175    into the second directory structure, say
 176
 177       /orca/branches
 178       /orca/tags
 179       /orca/trunk
 180
 181    and you didn't care about tags, then you could use as svn_url the
 182    URL
 183
 184       http://svn.orcaware.com:8000/repos/orca
 185
 186    and use . as import_dir.
 187
 188    In this case, the script will only check out the orca subdirectory.
 189    This is handy if the entire repository is very large and you don't
 190    want this script to check the whole repository under /repos out to
 191    load files into it.
 192
 193    The only caveat is that svn_url must exist already in the
 194    repository.  So in this case, you would have to already have
 195    created the orca subdirectory in the repository.
 196
 197 4) Decide on the tags you want on your directories.  If you don't want
 198    any tags, then ignore this step.
 199
 200    The script takes a -t command line argument that is a directory
 201    path relative to the svn_url that you supply to this script from
 202    step 3 above.  Again, the URL from step 3 does not need to be the
 203    URL of the root of the subversion repository, so you can work in
 204    the subdirectory just fine.
 205
 206    Look at the directories that will be loaded into the repository and
 207    come up with a Perl regular expression that matches only the
 208    portion of the directory name that identifies each directory.  You
 209    may need to rename your directories so that they contain a version
 210    number you can use to tag them properly.
 211
 212    The regular expression should be placed into the directory path
 213    given to -t surrounded by @'s.  Make sure to protect the regular
 214    expression from the shell by using quotes.
 215
 216    You can have multiple sets of regular expressions in the directory
 217    path.
 218
 219    There is no way to escape the @ characters.
 220
 221    Example:
 222
 223    For the Orca directories orca-0.18 and orca-0.27b2 I can use the
 224    regular expression \d+\.\w+.  I want the tags to be located in
 225    the tags/orca/VERSION_NUMBER directory.  So I would use:
 226
 227       -t 'tags/orca/@\d+\.\w+@'
 228
 229 5) Back up your Subversion repository in case you are not happy with
 230    the results of running the script or the script fails for some
 231    reason.
 232
 233    Example:
 234
 235    % /opt/i386-linux/apache-2.0/bin/apachectl stop
 236    % cd /export/svn
 237    % tar cvf repos_backup.tar repos
 238    % /opt/i386-linux/apache-2.0/bin/apachectl start
 239
 240 6) Run this script.  The first argument is the root of the Subversion
 241    package directory where you want to install the directories.  The
 242    directories are loaded in order that they appear on the command
 243    line.
 244
 245    Example:
 246
 247       svn_load_dirs.pl http://svn.orcaware.com:8000/repos \
 248          trunk/orca -t 'tags/orca/@\d+\.\w+@' orca-0.18 orca-0.27b2
 249
 250    The output from this script are:
 251
 252       A Added file or directory.
 253       U File's contents have been updated.
 254       d File or directory is deleted because an enclosing directory is
 255         deleted.
 256       D File or directory is deleted.
 257
 258 7) Check the results by either checking out a new tree and or browsing
 259    the repository with a browser.  If they are not what you want, back
 260    out the changes.
 261
 262    Example:
 263
 264    These commands back out the changes:
 265
 266    % /opt/i386-linux/apache-2.0/bin/apachectl stop
 267    % cd /export/svn
 268    % rm -fr repos
 269    % tar xvf repos_backup.tar
 270    % /opt/i386-linux/apache-2.0/bin/apachectl start