Subversion

From DreamHost
Jump to: navigation, search

Overview

Subversion (svn) is a versioning and revision control system. Developers can use Subversion to save current and historical versions of their site files which allows them to keep old versions of files and directories (usually source code) as well as a log of who, when, and why changes occurred. Since the old versions of the site files are stored in a repository, previous versions of those files can be restored at any time. Subversion is also a great tool that allows you to work on a development site while your current live site remains untouched. Once you have your changes perfected on the dev site, you can then commit them to the live site.

Creating a Subversion repository

  1. Add the website to your panel as Fully Hosted. View the Adding Domains & Subdomains article for detailed steps.
  2. Wait until this domain resolves online which may take a few hours. View the DNS propagation article for details.
    Once the domain is resolving online, you can proceed with creating your repository.
  3. Navigate to the (Panel > 'Goodies' > 'Subversion') page.
    01 Subversion.fw.png
  4. Update the following fields:
    • Project Name: Example name 'exampleProjectName'.
    • Project ID: Example ID 'exampleProjectID'.
    • Install to: Choose your domain, then click the blank text field to the right which auto-populates your Project ID.
    • Users: Using example user 'mysvnuser' and 'password12345'.
    • Visibility: Choose if you want this repo to be public or private.
    • HTTP/HTTPS: If you wish to use HTTPS, you must purchase an SSL Certificate.
  5. Click the Create my new project repository now! button to create the repository.
    A 'Success!' confirmation appears:
    02 Subversion.fw.png

How to connect to a Subversion repository

There are several ways to connect to your repository.

Connecting with your browser

  1. Navigate to the (Panel > 'Goodies' > 'Subversion') page.
    03 Subversion.fw.png
  2. Under the list of current projects, click the link for your repository.
    An authentication popup box then appears:
    04 Subversion.fw.png
  3. Use the username and password you created when setting up the repository.

This loads your repository within your browser to view.

Connecting with a client

You can also connect with a 3rd party client. TortoiseSVN is a very popular choice.

Connecting via SSH (command line)

There are many commands you can run via SSH to connect and manage your repository. Below are some of the most common commands.

Using the Checkout command

This command performs a checkout of your repostiory:

svn co http://www.websitehelp.support/exampleProjectID/

If you run this in your user's directory, a new folder is created. It's named the same as your projectID, and you have now created a 'Working Copy' of your repository on your local machine. For further information, please visit the following page:

Importing

Once the repository is created, you can add folders and files that you have in another location. It is better to use this method to keep the revisions number down when first creating the repository.

svn import /home/USERNAME/path/to/source file:///home/USERNAME/path/to/repository --message="Importing Project"

Updating

To ensure your Working Copy is using the most recent revision, run svn update:

svn update

For further details, please visit the following page:

Committing

After you have made all of your adjustments, you'll need to commit the changes to the repository.

svn commit -m "log messages"

This command commits all changes. The -m flag allows you to leave a message as to what and why you have committed in this specific revision.

Listing

Running the list command with the --verbose flag lists the following information:

  • Revision number of the last commit
  • Author of the last commit
  • Size (in bytes)
  • Date and time of the last commit
svn list --verbose

Loading a dumpfile

You may have an existing repository that you want to migrate to your Dreamhost svn repository. You must first make a dump file of your existing repository. Only then can load it into your Dreamhost repository.

  1. Dump your existing repository :
    svnadmin dump <path-to-repo> | gzip > dumpfile.gz
    Note2 icon.png Note: If you set up your repo using the Dreamhost Subversion panel, the repository will be under your user's /home/username/svn/repoID directory. For example:
    • svnadmin dump /home/exampleuser/svn/exampleProjectID/


  2. Upload dumpfile.gz to your home directory via FTP.
  3. Decompress the dumpfile before importing:
    gunzip -c dumpfile.gz | svnadmin load svn/repository_id

Using Subversion for Web development

Now that you have imported your files to the repository, you might be wondering how to leverage version control to your advantage. First thing you need to do is set up a Development area and a Live area.

For example:

  1. Log into your server via SSH.
  2. Backup your site by running the following command:
    tar -cvf yourwebsite.tar example.com/
  3. Checkout your repository to your development area:
    svn checkout http://example.com/yourProject $HOME/dev.example.com
  4. Checkout your repository to your live area:
    svn checkout http://example.com/yourProject $HOME/example.com

Publishing from Dev to Live

Using your dev site at dev.example.com, you can now make any necessary changes. Once all the changes are complete in your Dev area, you can then make them Live.

  1. Go to your dev directory:
    cd dev.example.com
  2. Commit your changes:
    svn commit -m "Your change log notes"
  3. Go to your live directory:
    cd ~/example.com
  4. Update the Live site:
    svn update

You may see the following error when updating from your dev site:

Conflict discovered in <filename>
Select: (p) postpone, (df) diff-full, (e) edit,
        (mc) mine-conflict, (tc) theirs-conflict,
        (s) show all options:

If you type in the letters tc and click 'Enter' on your keyboard, all changes made in your Dev site are updated to your Live site. View the following page for further details:

Your changes are now live.

Automatic Post-commit Checkout

Additionally you can configure your site to automatically check out the current sources from your repository by using Subversion's "hook scripts". In short, the script called 'post-commit' is executed by the web server each time new sources are checked into your repository.

Be advised that when the web server executes this script, it is running in the security context of the dhapache user. This user does not and should not (for security reasons) have the necessary permissions to modify the files in your web site's directory. As such, you must arrange for the post-commit script to run the update in the security context of a user with the privileges necessary to update your site.

Using post-commit.tmpl

  1. Log into your server via SSH.
  2. Navigate to the following file:
    cd $HOME/svn/<repository_name>/hooks/post-commit.tmpl
  3. Open that file in a text editor. The following contents are set by default:
    #!/bin/sh
    
    REPOS="$1"
    REV="$2"
    
    "$REPOS"/hooks/mailer.py commit "$REPOS" $REV "$REPOS"/mailer.conf
    
  4. Change it to the following making sure to update the two email addresses to yours:
    #!/bin/sh
    
    REPOS="$1"
    REV="$2"
    
    /usr/share/subversion/hook-scripts/commit-email.pl --from svnaddress@example.com "$REPOS" "$REV" youremail@example.com
    
    Note2 icon.png Note: The --from section is crucial because the script will fail if it does not have a "from" address. Any email address will do. You can also change the second address to send to any email you like.


  5. Save the file as post-commit (removing the 'tmpl' file extension).
    Note2 icon.png Note: When you save this as the new file name in your text editor, the permissions change from dhapache to your user, which is what you want. Confirm that the new post-commit file is now owned by your user before continuing.


  6. As the new file should now be owned by your user (NOT dhapache), run the following command:
    chmod a+x post-commit
  7. Try a commit with your svn repository. You should now receive a commit notification to your email address.

Versions of Subversion on DreamHost

To find out which version of Subversion you have on your server, log in to the server via SSH and run the following command:

svn --version

If you would like to install a newer version of subversion (e.g., for repository syncing), then you will need to visit this page and download the subversion-x.x.x.tar.bz2 file:

Upgrading to the newest Subversion

Compiling subversion is pretty straightforward but you may encounter some compilation errors depending on the version. In general, follow these steps to compile and install subversion locally:

mkdir tmpwork
cd tmpwork
wget http://apache.spinellicreations.com/subversion/subversion-x.x.x.tar.gz
tar -xjf subversion-x.x.x.tar.bz2
cd subversion-x.x.x
./configure --prefix=/home/{username} --with-ssl [See version specific config information below]
make
make install

This installs the new subversion into your user directory. You'll need to change the path to include your ~/bin directory to use the new binaries. To do that, run the following command in your terminal:

alias svn='/home/USERNAME/bin/svn'

Troubleshooting

301 errors

If you are receiving 301 errors saying "repository has been moved permanently to [some other url]", then check these things:

  • Make sure that you haven't created your repository called "svn" or inside of a directory called "svn".
  • Make sure you don't have .htaccess rules above the subversion directory that are causing any kind of re-write (like WordPress). This includes having DreamHost automatically add 'www.' to your URL. View the Removing the "www" from your domain article for further details.
  • If you're running WordPress and want to have your SVN repository excluded from the WP redirection, simply add these rules to your .htaccess:
 # BEGIN WordPress
 <IfModule mod_rewrite.c>
 RewriteEngine On
 RewriteBase /
 RewriteCond %{THE_REQUEST} SVNRepo
 RewriteRule . - [L]
 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteCond %{REQUEST_FILENAME} !-d
 RewriteRule . /index.php [L]
 </IfModule>
 # END WordPress
Note2 icon.png Note: Make sure to change the end of line #5 to the subversion directory name in your WordPress directory.


Import errors

If you are seeing errors where import is working for some but not all files, try disabling your anti-virus software.

File ownership problems

On DreamHost servers, subversion runs as the dhapache user. If you create a file, it is owned by yourusername, not dhapache and subversion can't read it. It is pretty easy to have this happen.

Once dhapache has lost ownership of the file, your repository becomes unmodifiable and your users will get "permission denied" errors when they try to commit.

Fixing ownership problems

If your repository becomes corrupted through bad ownership, try the following:

  1. Navigate to the (Panel > 'Goodies' > 'Subversion') page.
  2. To the far right of your repository, click the Edit button.
  3. Add a new user and password.
  4. Click the Update my repository now! button to save.

In the process of adding a new user, the DreamHost job will recursively change file ownership for the whole repository back to dhapache.

If this doesn't work, you may have to dump, recreate and reload your repository.

Considerations and Caveats

Hastily-made repositories often don't work

If you create your repository before its URL has been created and is resolving online, you may have an inaccessible repository. Assuming it doesn't yet contain any information, just delete it and recreate it.

Alternatively, you may experience a DNS propagation delay if you can access your repository via http within the DreamHost system, but see an empty directory from outside DreamHost. If you can't wait, try querying the DreamHost DNS servers for your IP and use a local hosts file or NetInfo to temporarily resolve your svn host. Remember to undo this when DNS records have propagated.

Hosting more than one Subversion domain

You can host multiple svn domains and subdomains under one DreamHost account, but they are not completely independent. In particular, all repositories created with the same FTP user share the same namespace, even if under different URLs. With a single FTP user, a given repository name can only be used once for all svn domains.

If you create http://svn1.example.com/repo, you cannot have a second repository named http://svn2.example.com/repo. If you do configure http://svn2.example.com/repo, it is a second name for the same repository, with a separate set of permissions. If you must create two repositories with the same name, create a second FTP user.

Hosting subversion for a domain that is not on DreamHost

If you have a domain which is not hosted on DreamHost and you want to set up Subversion on a subdomain of that domain, it will not work with a normal setup.

You must configure a subdomain such as realsvn.exampleOnDreamhost.com, then create a subdomain for svn.exampleNOTonDreamhost.com.

Finally, create a mirror to that domain from the domain you want. Make sure you wait for DNS propagation to occur before testing everything.

Handmade repos are read-only

If you find that you have to tweak and reload your dumpfile a few times, it can be handy to use the CLI tools (e.g., rm -rf and svnadmin create) to wipe and recreate your repository until you get it right. But then you'll want to use the panel to delete and recreate your repository. Your test repositories will not function properly in production as they won't permit any changes.

The panel creates the repository with dhapache as the owner, and the reponame.access and reponame.passwd files with dhapache as the group. Trying to create your own production repo with svnadmin create is futile because you don't have authorization to change those ownerships and group memberships (and you're not a sudoer).

Important icon.png Important: Don't overwrite dhapache files. Overwriting files causes them to have your user's group instead of dhapache. If your repository is relatively mature when you make this mistake, and you have no backup, you won't have any options.


Some clients require MD5 passwords

If you get "access denied" warnings, you may need to use MD5 passwords instead of the standard variety created by the DreamHost panel. Use htpasswd -nm username to generate the entry (ala username:passwd-hash) for your reponame.passwd file, then use an editor to replace your standard password entry.

Don't overwrite your reponame.access and reponame.passwd files with echo "username:passwd-hash" > reponame.passwd. Overwriting files causes them to have your user's group instead of dhapache, leaving your repository in a read-only or inaccessible state.

Interfacing with Subversion from PHP

You'll need to install the PECL extension SVN:

.htaccess security

Subversion can be a very useful tool for developing Web sites or Web-based applications. You may wonder, though, how that would work. After you commit your changes to your repository, how do you have them reflected on your site? The easiest method is to have your site's directory on the server set as a working copy checked out from your Subversion repository. If you elect to do this, be certain to modify your site's .htaccess to prevent users from browsing Subversion's control files. Something simple in the root of your site such as the following should suffice:

RedirectMatch 403 /\.svn

Using Apache basic authentication

The prior section's steps require each user to have a Unix account with shell access so they can log in via SSH. However, the DreamHost panel provides a way to create user accounts only for Subversion.

But for those accounts, if you want to specify who has read vs. read-write access and/or per-directory of your repository, you must manually edit the .access file as described in the latest Subversion manual on "Per-directory access control" and DreamHost's implementation of this feature. You can manually add and administer the usernames and passwords for Subversion by using htpasswd to add/edit users to the .passwd file for your repository.

Note after manually editing either the .access or .passwd files

  • The file's group changes from dhapache to whatever the auto-generated group for your account is, which prevents the Apache module from being able to read the files, so you then need to change the permissions so that they can be read by Apache(do "chmod 644").
  • You will also need to be prepared that if you now use the DreamHost control panel to change settings (at least if you make changes to the user list), the panel not only reverts the file permissions back to dhapache but also overwrites both files, overwriting any changes you made to them. So you'd should always have a backup to reconstruct anything important that might get overwritten.
Note2 icon.png Note: "chmod 644" is giving "world" read access to those files which may be a security risk. While these files won't be accessible via http (unless you also publish your svn/ which would likely be unwise), these files are accessible to other shell users to your account and MAYBE by other DreamHost account holders on your shared host. Therefore, for real security, you should not use http, but instead https (which is also the only option if accessing via WebDAV) or SSH.


See also

GUI applications for Mac OS X

GUI applications for Windows