notes/svnsync.txt

   1                            ==== What Is It? ====
   2
   3 svnsync is a tool for creating and maintaining read-only mirrors of
   4 subversion repositories.  It works by replaying commits that occurred
   5 in one repository and committing it into another.
   6
   7                            ==== Basic Setup ====
   8
   9 First, you need to create your destination repository:
  10
  11 $ svnadmin create dest
  12
  13 Because svnsync uses revprops to keep track of bookkeeping information
  14 (and because it copies revprops from the source to the destination)
  15 it needs to be able to change revprops on your destination repository.
  16 To do this you'll need to set up a pre-revprop-change hook script that
  17 lets the user you'll run svnsync as make arbitrary propchanges.
  18
  19 $ cat <<'EOF' > dest/hooks/pre-revprop-change
  20 #!/bin/sh
  21 USER="$3"
  22
  23 if [ "$USER" = "svnsync" ]; then exit 0; fi
  24
  25 echo "Only the svnsync user can change revprops" >&2
  26 exit 1
  27 EOF
  28 $ chmod +x dest/hooks/pre-revprop-change
  29
  30 $ svnsync init --username svnsync file://`pwd`/dest \
  31                                   http://svn.example.org/source/repos
  32 Copied properties for revision 0
  33 $
  34
  35 Note that the arguments to 'svnsync init' are two arbitrary repository
  36 URLs.  The first is the destination, which must be empty, and the second
  37 is the source.
  38
  39 Now you can just run the 'svnsync sync' command to synchronize pending
  40 revisions.  This will copy any revisions that exist in the source repos
  41 but don't exist in the destination repos.
  42
  43 $ svnsync sync file://`pwd`/dest
  44 Committed revision 1.
  45 Copied properties for revision 1.
  46 Committed revision 2.
  47 Copied properties for revision 2.
  48 Committed revision 3.
  49 Copied properties for revision 3.
  50 ...
  51
  52                               ==== Locks ====
  53
  54 If you kill a sync while it's occurring there's a chance that it might
  55 leave the repository "locked".  svnsync ensures that only one svnsync
  56 process is copying data into a given destination repository at a time
  57 by creating a svn:sync-lock revprop on revision zero of the destination
  58 repository.  If that property is there, but you're sure no svnsync is
  59 actually running, you can unlock the repository by deleting that revprop.
  60
  61 $ svn pdel --revprop -r 0 svn:sync-lock file://`pwd`/dest
  62
  63                                ==== FAQ ====
  64
  65 Q: So what can I do with this thing anyway?
  66
  67 A: Well, anything that's read-only.  As long as you don't commit changes
  68    to the destination repository you're all set.  This means destination
  69    repositories are good for providing offsite mirrors, read-only mirrors,
  70    etc.
  71
  72 Q: What if I want to check out from a mirror, but commit to the master?
  73
  74 A: That's possible, but requires some gymnastics.  You see, each repository
  75    has its own UUID, which is stored in the working copy, so if you check
  76    out from the mirror, and then do a 'svn switch --relocate' to point to
  77    the master it'll error out.  To make this work you need to make sure that
  78    the mirrors have the same UUID as the master.  You can set a repository
  79    UUID via the following technique:
  80
  81 $ cat - <<EOF | svnadmin load --force-uuid dest
  82 SVN-fs-dump-format-version: 2
  83
  84 UUID: d48dd586-eb1d-0410-b581-e6e13afcedeb
  85 EOF
  86
  87    Once both the mirror and master repositories have the same UUID you can
  88    safely check out from the mirror and commit to the master, all you have
  89    to do is do a 'svn switch --relocate' to point your working copy to the
  90    master before a commit.
  91
  92    Note that you should NEVER commit changes to a mirror other than
  93    via svnsync, so to avoid accidentally doing so you may want to add
  94    a start-commit hook script that disallows commits from users other
  95    than the one you run svnsync as, and a pre-lock hook script that
  96    disallows all filesystem lock requests (svnsync will never create
  97    these locks, but its attempt to commit can be blocked by them).
  98
  99 Q: What version of Subversion is required to use svnsync?
 100
 101 A: The source repository must be running Subversion 1.4 or newer, since
 102    svnsync uses a new RA layer command that was added in 1.4.  On the other
 103    hand, the destination repository can be any version of Subversion, since
 104    all svnsync is doing is committing changes using the regular RA APIs.
 105
 106 Q: Do I need to run svnsync on the same machine as one of the
 107    repositories?
 108
 109 A: While you do need direct access to the destination repository to
 110    set up a pre-revprop-change hook script, after that point svnsync
 111    communicates with both repositories through the same "repository
 112    access" layer that svn uses to connect to remote repositories. So
 113    svnsync does not have to be run on the same machine as either
 114    repository; it can communicate with both repositories over any of
 115    Subversion's RA protocols (svn://, svn+ssh://, http://, https://,
 116    or file:///).  In fact, you don't need any special permissions on
 117    the source repository at all.
 118
 119 Q: How does svnsync deal with parts of the master repository that I'm not
 120    authorized to read?
 121
 122 A: svnsync will simply not copy parts of the repository that you
 123    cannot read; files copied from "private" parts of the repository
 124    into "public" parts will look as if they have been added from
 125    scratch.  If a revision only modifies files that you cannot read,
 126    it will appear to be empty.  (Just like with "svn log", log
 127    messages from revisions you cannot read part of will be empty.)
 128
 129 Q: Can I mirror a subdirectory of a master repository?
 130
 131 A: As of Subversion 1.5, it is possible to limit svnsync to a subdirectory
 132    of the master repository.
 133    This is most useful when the master repository is organized in projects,
 134    and you want to sync only one project.
 135    Example showing svnsync of project1 in the master repository:
 136    /project1
 137       /branches
 138       /tags
 139       /trunk
 140    /project2
 141       /branches
 142       /tags
 143       /trunk
 144
 145    The following commands will sync all changes in /project1 to the target
 146    repository:
 147 $ svnsync init file://`pwd`/dest http://svn.example.org/source/repos/project1
 148 $ svnsync sync file://`pwd`/dest
 149
 150    Note: this syntax only allows you to limit the scope of svnsync to
 151    /project1. It does not:
 152    - allow you to sync two or more projects from the master repository.
 153    - recognize renames of project1. Example, if the original name of project1
 154    was secretproject, only the changes starting from the revision in which the
 155    rename to project1 was committed will be synced.
 156
 157    If you need any of these abilities right now, you may want to look into SVK
 158    (http://svk.bestpractical.com/).
 159
 160 Q: What happens when I change a revprop on the master server?
 161
 162 A: That depends, did you change it on a revision that had already been
 163    mirrored or one that's still waiting to be mirrored.  If the revision
 164    hasn't been mirrored yet, the new revprop will just get copied across
 165    normally when the next sync happens.  If not, then you've got a small
 166    problem.  You see, since revprops aren't versioned, there's no way to
 167    detect (via the Subversion RA APIs anyway) that it's been changed, so
 168    the next time you run a sync svnsync has no way to tell that it has
 169    changed.  There is a way for you to build your own solution though,
 170    just use the 'svnsync copy-revprops' command.  The usual technique is
 171    either to put an explicit call to it in your master repository's
 172    post-revprop-change script, or to have the post-revprop-change script
 173    record the fact that a change occurred, and then later on have some
 174    job look through the list of changes and copy them over for you.