Subversion User Guide Windows

THL Toolbox > Developers’ Zone > Server Issues > Subversion User Guide > Subversion Guide (Windows)

Subversion Guide for THL Users: Windows Version

Contributor(s): Dan Haig, Steve Weinberger.

This document is an introduction and user guide for Subversion (svn), the version control system that developers working on the Tibetan and Himalayan Library website are required to use. As indicated, these are the specifics for Windows users. Mac users should obtain the respective Mac document. Unix users will no doubt figure it out for themselves from the following.

If you have any questions, please contact the THL Server & Account Issues Contact.

Contents

  1. Introduction
  2. Obtaining, installing and configuring the "TortoiseSVN" gui client application for Subversion
  3. Using TortoiseSVN to do the initial checkout or “download” of the THL website files from the Subversion repository
  4. Normal use of TortoiseSVN to do work and commit changes to the repository
  5. Deploying to the www/live/production server
  6. Recovering older versions, conflict resolution, and other details

Introduction

Welcome to the world of version control. It’s worth the hassle, which is pretty minimal given the significant improvements that Subversion (or svn) has made over its antecedent (and still industry standard) cvs. If you are familiar with cvs, the switch to Subversion will be pretty straightforward, altho a few seemingly familiar cvs commands do very different things in svn, so watch it.

What does Subversion do? Here’s a good summary, from the external link: Subversion book (very useful and available free online):

Subversion is a free/open-source version control system. That is, Subversion manages files and directories over time. A tree of files is placed into a central repository. The repository is much like an ordinary file server, except that it remembers every change ever made to your files and directories. This allows you to recover older versions of your data, or examine the history of how your data changed. In this regard, many people think of a version control system as a sort of “time machine.”

If you are new to the whole concept of version control, it goes something like this: the THL website contains a large number of files and directories that several people have the power to edit or otherwise change. This is risky - you or somebody else might inadvertently destroy valuable work, and our only recourse would be to beg the Library admins to go diving into the tape backups, which is a significant hassle for them and not liable to happen as quickly as you would like, and in the meantime the hole you’ve made in the THL dangles in the wind for all to see. Uncomfortable, no? But with Subversion you can quickly ‘go back in time’ to retrieve lost data. Of course using this safety net requires a little work up front, so please follow the directions here and within an hour you should be back to doing your real work.

Obtaining, installing and configuring a client application

If you are able to use command line for all your natural svn needs (or would like to learn: see the book url listed above), more power to you. But this section is about using a client gui application, similar to an FTP program, to access the Subversion repository.

The recommended Subversion client software for Windows is TortoiseSVN. TortoiseSVN is very easy to use - once you have it installed, all you'll need to do is go to your folders/files using Windows Explorer and use the right click to choose whichever of the offered TortoiseSVN commands you want to use for said folders/files.

Here are the steps to download and configure your TortoiseSVN client:

  1. Download the application. The external link: TortoiseSVN application NOTE: As of 10-17-2016, you need to install an older version of TortoiseSVN from external link: here:
  2. Double click the installer exe and follow the presumably familiar process of installing the application.
  3. When finished installing, right click on any folder and make sure that the TortoiseSVN choices appear in the popup. If so, you are ready to move on.

Using TortoiseSVN to do the initial checkout or “download” of the THL website files from the repository

The Subversion repository for the THL lives on UVa’s main Subversion server, titan.lib.virginia.edu (which has an alias, subversion.lib.virginia.edu).

The THL repository is huge - some 18 gigabytes w/o the extra stuff subversion uses to manage the repository, which can as much as triple the memory requirements - so rather than checking out the whole repository, it has proven quicker and easier to pull out pieces that are relevant to any given user. Please note however that you can't just check out one directory four levels down - you need to check out its parent directories first, and maintain the same structure of the THL directory tree (you won't have to check out all of the content for all of those - more below).

Here is how most of us would want to proceed with getting set up locally with relevant parts of the THL from the svn repository:

  1. Create a folder named “thdl-quandu” on your hard drive.
  2. Right-click that folder and select the popup menu choice “SVN Checkout”.
    1. In the “URL of repository” field, enter this: external link: https://subversion.lib.virginia.edu/repos/thdl-quandu/
    2. The “Checkout directory” field should have the directory path to the folder named “thdl-quandu” that you just created. If it does not, click on the button with three dots (…) to the right of the field and navigate to the “thdl-quandu” folder you just created.
  3. Click in the box to the left of "Only check out the top folder"; a check mark will appear in the box. Note: with the current version of TortoiseSVN this might now be replaced by a pulldown menu called "Checkout depth"; select "only file children" This is very important!!! If you don't click in this box you will download the entire contents of THL, which you do NOT want to do (and which you probably don't have space for on your hard drive).
  4. Click OK.
  5. When TortoiseSVN asks for user/pass, enter your UVa user id and the password you created when you logged into scripta.lib.virginia.edu. If this doesn't work, contact Steve Weinberger for help. (If you need to change or clear your password, use: Settings > Saved data > Authentication data > Clear; this will bring up a dialogue box next time you you try to log in, and you can enter your new login/password).
  6. A dialog box will open that shows the files being downloaded. When it is finished, the bottom line will read “Completed. At revision: ####.” Click OK.
  7. On your hard drive, the “thdl-quandu” folder should now appear with an icon of a white check mark inside a green circle.
  8. Right-click on the “thdl-quandu” folder and point to "TortoiseSVN" and then click on “Repo-browser”
  9. Click on the plus sign (+) to the left of the folder named external link: https://subversion.lib.virginia.edu/repos/thdl-quandu/.
  10. Right-click on the folder named “trunk” and click on “Checkout…”
  11. The “URL of Repository” field should have a directory path that ends with thdl-quandu/trunk.
  12. For the “Checkout directory” field, click on the button with three dots (…) to the right of the field and navigate to the “thdl-quandu” folder you just created. The directory path will now appear in the “Checkout directory” field. At the end of the directory path, after thdl-quandu, add trunk.
  13. Click in the box to the left of "Only check out the top folder"; a check mark will appear in the box. Note: with the current version of TortoiseSVN this might now be replaced by a pulldown menu called "Checkout depth"; select "only file children" This is very important!!!
  14. Click OK.
  15. If there is a dialog box that reads "The folder such-and-such does not exist. Would you like to create it first?" click Yes.
  16. A dialog box will open that shows the files being downloaded. When it is finished, the bottom line will read “Completed. At revision: ####.” Click OK.
  17. On your hard drive, within the “thdl-quandu” folder, a folder named “trunk” with an icon of a white check mark inside a green circle should appear.

Selecting only the top folder will provide the "trunk" folder (which represents the core version of the repository – "branches" will be made later to deploy pieces of the repository to the live web site) and whatever incidental loose files are at the top level of the site (index.html, etc), but it does not provide all of the subfolders, which you don't want right now unless you are prepared to take in the entire THL site. More importantly, your new "thdl-quandu/trunk" folder has a .svn folder, so it is ready for further Subversion directives.

  1. To export (from the repository to your hard drive) any sub-directories of the thdl, right click in the thdl-quandu/trunk directory you've just pulled down to your hard drive, choose Tortoise SVN -> Repo-browser. This repository browser shows you the tree of folders and files at external link: https://subversion.lib.virginia.edu/repos/thdl-quandu/trunk/. Right click on any directory or file you want to checkout from the repository, and choose "Checkout…". The dialog box that pops up will show that directory as URL of Repository; you need to specify the Checkout directory, which is where you want to store it locally, for instance, C:thdl stuffTHDL-SVNtrunkcollectionscultgeobhutan. If you have not created the bhutan folder, svn will ask you if you want it to do so for you; say yes, then all the files and subfolders of 'bhutan' will be delivered to your local version. Note that you can continue to use the "only check out the top folder" option to get just the folder if you don't want all of the subfolders.

It bears emphasizing that you *must create your local folder tree exactly as it is in the repository - you must not have two folders, one from the top level and one from the sixth level, sitting alongside each other at the top level of your local version.

Congratulations - you’re now in a position to get to work!

_____

Here's how to get ALL of the thl files from the repository and onto your computer:

  1. Create a fresh “thl” folder on your hard drive.
  2. Right click that folder, select the popup menu choice, “SVN Checkout”. It will ask you for “URL of repository” - give it this: external link: https://subversion.lib.virginia.edu/repos/thdl-quandu/
  3. Under “Checkout directory”, tell it where on your hard drive you want to put the repository files.
  4. TortoiseSVN asks for user/pass, give it your usual uva login. If this doesn't work, contact Steve Weinberger (external link: snw8f@virginia.edu) for help.
  5. TortoiseSVN then checks out a copy of all of the files and folders from the repository to your hard drive. When the full THL site is checked out it takes quite a long time - potentially overnight or longer - so be prepared.

Normal use of TortoiseSVN to do work and commit changes to the repository

So, you have TortoiseSVN up and running, and a copy of relevant parts of the THL on your hard drive. Let’s hack some code.

You’ll notice, in the top level of the thdl-quandu/trunk directory you checked out, a file called svn-guinea-pig.txt. This is your guinea pig for Subversion experiments. Please be sure you can do the following on test.txt *before* working on real THL files.

#Open svn-guinea-pig.txt, make some changes to it, then save and close the file.

  1. Look in the thl folder now and you’ll see that svn-guinea-pig.txt has a red exclamation point, which indicates that it is no longer identical to the version in the repository. Right click the file, in the Subversion menu select “SVN Commit…”.
  2. In the box that pops up, you can enter a Message to be attached to your commit. When you or someone else needs to look thru the log of the file, it helps to see the messages saying what changes happened at each stage. So - enter your message then click OK. Subversion then commits your changes to the repository, along with your message. When you look in your local thdl-quandu/trunk folder, you’ll see that the red exclamation point has turned into a green “check”, which means your local version and the repository version are in sync.

That’s basically it for making changes. Now however you need to deploy your changes to the server environment (dev, staging, or production) so they appear online.

Creating Tags

After you make major changes, add a feature, or fix a bug and then commit files and folders to the repository, you need to create a tag, which is a snapshot of the repository at a given time. This provides benchmarks of the repository at various points in the past that we can go back and look at later if something is wrong or we have questions about particular files or folders.

To create a tag:

  1. In your subversion gui just right click on www/trunk and choose "copy"
  2. For the destination enter www/tags/release-x.x.x
  3. The x-s correspond to the version number
    1. If the changes you made represent a major overhaul, increase the first number by 1
    2. If you added a feature, increase the second number
    3. If you fixed a bug, increase the third number by 1

  • For example, if the most recent tag is release-1.2.3 and you fixed a bug in, say, the Place Dictionary, then create a new tag named release-1.2.4. If the most recent tag is release-1.2.3 and you added a feature in, for example, the Tibetan text catalog system, then create a new tag named release-1.3.3. If the most recent tag is release-1.2.3 and you made a major overhaul, then create a new tag named release-2.2.3.

Deploying to www/live/production server

You first commit the changes you made to the file or folder on your hard drive to the Repository. After this, you need to deploy the file or folder to the server environment so that it displays online.

Note that none of us has write permissions on orion for /lv6/thdl/ (which is where www.thdl.org's version resides), which is owned by root to keep people from working around the version control. This environment can only be affected by us via Subversion. No more FTP'ing to the server.

In brief, the new deployment workflow goes like this:

  1. Update your version of thdl-quandu/trunk/svn-guinea-pig.txt (always update before working on a file: right click the file icon, select SVN Update, let it do its thing…)
  2. Do your edits.
  3. Commit your changes to the repository
  4. Your changes will be automatically pushed to production when you commit them.
  5. Go check your changes now at external link: http://www.thlib.org/svn-guinea-pig.txt
  6. Celebrate your mastery of the new system.

Note that you *can logon to orion and read the files that are in lv6 (www), to check to be sure your changes really made it thru the system, but you won't be able to edit them there.

Re-versioning, conflict resolution, dumpster diving and other details

Content to come - please contact me if you need immediate help in these areas.

  1. Use "SVN Update" even while you are working on a file to merge changes from the repository version to your version. Then click "SVN Commit" to commit your version (which now is a combination of the latest version on the repository and on your hard drive).
  2. Resolving conflicts: do SVN Commit. When the dialog box opens, right-click on the file name and point to "Compare with Base." This will open a TortoisMerge dialog box. The "Working Base" is the repository version; the "Working Copy" is your version. Use the green up and down arrows ("Previous difference" and "Next difference") in the menu bar to navigate to each conflict. Right-click on the one you want to keep and point to "Use this text block."

Provided for unrestricted use by the external link: Tibetan and Himalayan Library