Home > Project documentation > Documentation for encoders

Access Files from the Subversion Repository

roseList documents mentioning Access Files from the Subversion Repository

Introduction

This manual explains how to share files using a subversion (SVN) repository. For a summary of commonly used commands, see Commands.

About the Subversion Repository

All of MoEML’s project files, including programming logic (XQuery, XSLT, etc.), are stored in an SVN repository. This repository maintains a copy of every file so that, if needed, a previous version of the website can be accessed. It also helps prevent versioning conflicts when multiple editors work on the same file.
To access data from the repository, use an SVN command-line client. This method may seem old-fashioned, but it is an easy process that remains consistent across different platforms (Windows, Mac, etc.). It also allows experienced users to run functions like svn log to see a list of all the changes made to the repository.
This manual provides instructions for Linux, Windows and Mac users. See also tips and tricks for using SVN.

Using SVN on Linux

At HCMC, SVN is already installed on Linux. Editors working from their own computers will need to install SVN from the repositories of their own distribution.

Access Files from the Repository on Linux

First, create a directory for MoEML’s files and check out those files from SVN:
  • Open a command line window (terminal) by pressing Ctrl + Alt + T. The command line should open the home directory. MoEML files will be saved here.
  • Make a new directory by typing mkdir london and pressing the return key.
  • Change from the home directory to the london directory by typing cd london and pressing the return key.
  • Check out MoEML’s files by typing svn checkout https://hcmc.uvic.ca/svn/london/db/data . and pressing the return key. Make sure to include the s in https and the space + period at the end (after data).
  • The above commands can be copied and pasted into the command line to avoid typos.
The command line entries should look like this:
linux_cd_mkdir_london.png
linux_svn_checkout_pre.png
All the MoEML file names will scroll past as they are downloaded:
linux_svn_checkout_during.png

At the end of this list, the command line will show which revision was checked out:
linux_svn_checkout_post.png

The revision number indicates the state of the repository. In the above example, seventy-five changes have been committed to the repository since it was set up. Every time a new change is committed to the repository (see below), the revision number will increase by one.
There is now a complete copy of MoEML’s files on your hard drive. Files can be edited in this location using Oxygen. Please remember to validate the files as you update them: invalid XML files cause problems for the website.

SVN Update on Linux

Since multiple editors will be adding, updating, and sometimes deleting MoEML’s files from different locations, editors should make regular SVN updates. Update your local files by typing svn update into the command line and pressing the return key. MoEML recommends that an update be performed at the start of every session. See the example below:
linux_svn_update.png

In this example, a change has been made: a new file has been added (this is indicated by the A next to it; updated files are indicated with a U and deleted files with a D). Note that the revision number is incremented every time a commit is made; this repository is at revision number 1043, so 1043 commits have been made.

SVN Commit on Linux

Permissions are required to commit files to SVN. To obtain permission, contact the MoEML team.
When changes are made to local files, they will need to be committed (uploaded) to the repository with the commit command:
  • In the london directory (see above), type svn commit and press the return key.
  • The command line will generate a basic text editor: give a brief, specific description of the changes made to the documents listed below. For example, Updated broken ref links in data/info/website_structure.xml. Then press Ctrl + O to create a file name for the revision in the repository, followed by the return key. Then press Ctrl + X to exit the text editor.
  • If SVN asks you for a password, give your netlink password (the first time your password is given, it may fail since SVN defaults to the user name on your local computer first; in that case, SVN will also ask for a user name—use your netlink user name). Once SVN confirms that you have rights to commit to the repository, it will upload the changes:

linux_svn_commit.png

The system has committed the changes and the revision number is now 76.

Add Files to the Repository on Linux

To add a new file to the repository, make sure the file is valid and follows MoEML’s encoding practices. Also double-check that the file is saved in the correct folder.
In the london directory, type svn add, then a space, and then the file name. For instance, a file called test.xml located in the info folder should appear as follows:
linux_svn_add.png

The command line responds by echoing the folder and file name with an A in front of it.
Now commit the change to the server (see above); nothing is sent to the repository without an svn commit:
linux_svn_commit_addition.png

The command line will confirm that the revision has been committed.

Delete Files from the Repository on Linux

Use caution when deleting files from SVN: deleted files can be recovered, but recovering files is a time-consuming process. To delete a file, type svn delete, then a space, then the file name (in this example, info/test.xml):
linux_svn_delete.png

Note that this process also deletes the local copy of the file.
linux_svn_commit_deletion.png

Using SVN on Windows

Obtain a command-line client from CollabNet. Registration is required to download the program, but there is no cost. Make sure to download the correct version; there are versions for 32-bit and 64-bit Windows. Once the program is downloaded, install it by double-clicking the downloaded installer and following its instructions.

Access Files from the Repository on Windows

Next, open a command window (terminal) by clicking the start menu and typing cmd into the search box and pressing return. This action should bring up a terminal window:
win_start_menu.png
win_cmd.png

win_terminal.png
The terminal window opens in the home folder (C:\Users\[username] on Windows 7). Save MoEML’s files here in a new folder called london:
  • Make a new directory by typing mkdir london into the command line and then pressing the return key.
  • Change from the home directory to the london directory by typing cd london followed by the return key.
  • Check out the files by typing svn checkout https://hcmc.uvic.ca/svn/london/db/data . followed by the return key. Make sure to include the s in https and the space + period at the end (after data).
The above commands can be copied and pasted into the command line to avoid typos. The command line entries should look like this:
win_cd_mkdir_london.png
win_svn_checkout_pre.png
All the MoEML file names will scroll past as they download:
win_svn_checkout_during.png

At the end of this list, the command line will show which revision was checked out:
win_svn_checkout_post.png

The revision number indicates the state of the repository. In the above example, seventeen changes have been committed to the repository since it was set up. Every time a new change is committed to the repository (see below), the revision number will increase by one.
There is now a complete copy of MoEML’s files on your hard drive. Verify this by opening Windows Explorer and navigating to the location they were checked out (C:Users/[username]/london):
win_explorer_tree.png

Files can be edited in this location using Oxygen. Please remember to validate the files as you update them: invalid XML files cause problems for the website.

SVN Update on Windows

Since multiple editors will be adding, updating, and sometimes deleting MoEML’s files from different locations, editors should make regular SVN updates. Update your local files by typing svn update into the command line and pressing the return key. MoEML recommends that an update be performed at the start of every session. See the example below:
win_svn_update.png

In this example, a change has been made: a new file has been added (it has A next to it; updated files are indicated with a U and deleted files with a D). Note that the revision number has changed to 18.

SVN Commit on Windows

Permissions are required to commit files to SVN. To obtain permission, contact the MoEML team.
When changes are made to a file, they will need to be committed (uploaded) to the repository with the commit command:
  • In the london directory (see above), type svn commit followed by a space and -m for message.
  • On the same line (without pressing the return key), type another space and, in quotation marks, a brief, specific description of the changes made to MoEML files.
  • Execute the command by pressing the return key.
For example, if updates were made to the file data/info/website_structure.xml, commit them by typing the following:
svn commit -m "Added copyright info to the header of website_structure.xml."
If SVN asks you for a password, give your netlink password (the first time your password is given, it may fail since SVN defaults to the user name on your local computer first; in that case, SVN will also ask for a user name—use your netlink user name). Once SVN confirms that you have rights to commit to the respository, it will upload the changes:
win_svn_commit.png

The system has committed the changes and the revision number is now 19.

Add Files to the Repository on Windows

To add a new file to the repository, make sure the file is valid and follows MoEML’s encoding practices. Also double-check that the file is saved in the correct folder.
In the london directory (see above), type svn add, then a space, and then the file name. For instance, a file called test.xml located in the info folder should appear as follows:
win_svn_add.png

The command line responds by echoing the folder and filename with an A in front of it.
Now commit the change to the server (see above); nothing is sent to the server without an svn commit:
win_svn_commit_addition.png

The command line will confirm that the revision has been committed.

Delete Files from the Repository on Windows

Use caution when deleting files from SVN: deleted files can be recovered but recovering files is a time-consuming process. To delete a file, type svn delete, then a space, then the file name (in this example, info/test.xml).
win_svn_delete.png

Then commit the change (see above). Note that this process also deletes the local copy of the file.
win_svn_commit_deletion.png

Using SVN on Mac OS X Mountain Lion and Mavericks

Mountain Lion and Mavericks users can access MoEML’s subversion repository in a similar way to the Linux users because both of these operating systems are Unix-based. There are, however, a few differences of which Mac users should take note.

Install SVN Command Tools on Mac

Though earlier Mac operating systems include subversion command tools by default, Mountain Lion and Mavericks do not. To test whether your operating system has these commands installed, follow these instructions:
  1. Open a terminal window in one of the following ways:
    1. Perform a Spotlight search for terminal by clicking the magnifying glass in the menu bar or by typing Command + Space. Once terminal is selected, press return key.
    2. Select Terminal from the Utilities folder in Applications.
  2. Type svn checkout and press the return key. If terminal responds that there are Not enough arguments provided, the subversion commands are already installed and you may proceed to the next section. If terminal responds that the command is not recognized, you will need to install them.
To install the subversion command tools using Homebrew, you will need to do the following:
  1. First make sure you have Homebrew installed on your machine by typing in brew help. If it is installed, you will get help instructions in terminal. If not, you will get a message telling you that the command is not found. In that case, install Homebrew by typing the following command: ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" and following the instructions. Note that a prerequisite to installing Homebrew is Xcode; if it is not installed on your machine, download it from the App store. For more on installing Homebrew, see these instructions.
  2. Once the Homebrew install is complete, type the following command: brew install svn, then press return. The process will take a few moments.
Another approach might be using Xcode:
  • First, download the developer tool Xcode from the App Store.
  • In terminal, type the following command: sudo rm -rf /Library/Developer/CommandLineTools then press return.
  • Then type in sudo xcode-select --install and press return.

Access Files from the Repository on Mac

Once you have made sure that your operating system has the necessary command line tools, you can check out MoEML’s files from the subversion repository.
First, create a directory for the files and check them out:
  1. Open a terminal window as above.
  2. The terminal will open by default in your home directory. To save MoEML’s files here, make a new directory by typing mkdir london and pressing return.
  3. Navigate to the london directory by typing cd london and pressing return.
  4. Check out MoEML’s files by typing svn checkout https://hcmc.uvic.ca/svn/london/db/data . and pressing return. Make sure to include the s in https and the space + period at the end (after data). You may wish to copy-paste the command from these instructions to avoid typos.
Once you’ve completed these steps, the MoEML file names will scroll past as they are downloaded. At the end of the list, terminal will report which revision was checked out. The files are now saved to your hard drive and can be edited using Oxygen.

SVN Update on Mac

Updating local files will be exactly the same for Mountain Lion, Mavericks and Linux users alike. Please see the Linux instructions above.

SVN Commit on Mac

Committing changes to files will nearly be the same for Mountain Lion, Mavericks and Linux users. The difference is that Terminal does not generate a basic text editor after the command svn commit. Instead, you will need to include the log message on one line as follows: svn commit -m "[short description of your changes]" (See Linux instructions above).

Add Files to and Delete Files from the Repository on Mac

Adding and deleting files will be the same for Mountain Lion and Mavericks users as it is for Linux users (See Linux instructions on adding files and instructions on deleting files), with the exception that after committing the files, the log message needs to be entered on the same line (see above).

SVN Tips and Tricks

This section includes a few terminal commands that may speed up your work with the subversion repository.

Create and Add New Files

When creating a new file for the project, even if it is just a word-processor file with notes in it, remember to give it a descriptive file name, and do not use punctuation or spaces in the file name. SVN can handle such characters in file and folder names, but files with these types of names can cause problems. For example, instead of Fred’s notes on Stow.odt, use Fred_notes_on_Stow.odt.
When creating a new file, first save it in the correct SVN folder and then enter svn add [the filename] to tell SVN that it should be managing the file. For instance, when creating a file in the documentation folder, first enter svn add documentation/Fred_notes_on_Stow.odt. The command line should respond with A (bin) documentation/Fred_notes_on_Stow.odt, meaning that SVN has accepted the file. Finally, the file needs to be committed with the command svn commit -m "[Short description of your changes]". Ex. svn commit -m "Added a file to documentation with my notes on Stow".
It may sometimes be necessary to add multiple formats of the same file; this is particularly applicable for image files. Suppose that the following image files exist: facsimile_agas.png, facsimile_agas.svg, and facsimile_agas.gif. Upload all three files at the same time by entering svn add db/site/images/facsimile_agas.* into the commmand line. The asterix symbol in this command means anything. By replacing the file extension with the asterix symbol, this single command adds the .png file, the .svg file, and the .gif file together. Thus, this command will trigger the following response:
svn add db/site/images/facsimile_agas.*
A (bin) db/site/images/facsimile_agas.png
A db/site/images/facsimile_agas.svgz
A db/site/images/facsimile_agas.gif
Finally, these file need to be committed with the command svn commit -m "Added new image of the Agas map in three formats."

Move a File

Before moving a file in SVN, make sure everyone who might have uncommitted changes to file being moved has committed their changes. Once you have done this, use the following command template in Terminal: svn mv [Insert current file url.] [Insert desired file url.]
This template assumes that you are in the correct data directory (i.e., that you have used Terminal to navigate to the folder that contains your MoEML files, usually named london). As the template indicates, the svn mv command consists of three parts: the preface svn mv, the file’s current url (i.e., where the file is located now), and the file’s desired url (i.e., where you want the file to be located).
Suppose that you want to move praxis.xml from its current location in the how_to folder to the info folder. The file’s current url is how_to/praxis.xml. In this hypothetical scenario, the file’s desired url is info/praxis.xml. To move the file, type the following command into Terminal: svn mv how_to/praxis.xml info/praxis.xml. SVN will respond by deleting the original file (in this example, how_to/praxis.xml) and adding a new one (in this example, info/praxis.xml). A dialogue that looks something like the following should occur in your Terminal window:
svn_mv.png
Finally, commit your change using the svn commit command. Once you commit your change, any team member who updates their SVN files will see that the original file has been deleted and that a new version of the file has been added in the specified location.

Auto-Completion at the Command Line

Commands must be typed precisely at the command line with the correct capitalization. For example, MyFile.odt is a different file from myfile.odt. However, the command line has a few helpful shortcuts. To automatically complete a command, press tab after entering the first two or three characters of a file name (enough to distinguish it from any other file in the folder). For example, typesvn add doc, then press tab. The command line should then complete the folder name: svn add documentation/. Then add Fre: svn add documentation/Fre and press tab. The command line should complete the rest of the filename: svn add documentation/Fred_notes_on_Stow.odt.

Recall Previous Commands

When working at the command line, it may sometimes be necessary to repeat the last command, or the last command with a small variation. It is possible to use the arrow keys on the keyboard to recall previous commands. For example, enter svn add documentation/Fred_notes_on_Stow.odt svn commit -m "Added a file to documentation with my notes on Stow." then press the Up arrow. This will retrieve the most recent command: svn commit -m "Added a file to documentation with my notes on Stow." and Press the Up arrow again to retrieve the command before that: svn add documentation/Fred_notes_on_Stow.odt. Use the Down arrow to scroll back through the commands until arriving at an empty prompt again.

Check the Status of Your SVN Tree

It frequently happens that new files are created and subsequently forgotten before being added to SVN. To find out what files have been modified in the current session, enter svn status. The command line will then return a list of file names. For example:
svn status
M static/css/global.css
? static/images/facsimile_page.svg
? static/images/facsimile_page.png
In the above list, the question mark symbol precedes file names that are not currently being managed by SVN. These files, should they be relevant to MoEML, need to be added and commited to SVN.
Finally, in the above list, M preceeds file names that have been modified in the current session but not commited to SVN. These files need to be commited to SVN.

Track Other People’s Work

The svn log command makes it possible to read SVN logs from recent commits, thereby enabling users to track each other’s work. To use this command, first enter svn log -l 20. (The character after the dash is a lowercase L and the succeeding number tells SVN how many logs to return.) In this example, SVN is being asked to return the most recent 20 entries; it is possible, however, to ask for more or less entries.To see the very latest log entry, enter svn log -r HEAD. To see the log entry for a specific revision, enter the number of the revision after -r. For example, svn log -r 1259 will return revision number 1259.
The command line will respond to these commands with a log entry or a series of log entries that look(s) like this:
r1259 | jenstad | 2013-05-06 16:31:33 -0700 (Mon, 06 May 2013) | 1
line Added a new file for Editorial practices for mayoral shows
editorial_practices_mayoral.xml in info.
Each individual log entry corresponds with a commit submitted to SVN. A log entry provides the revision number, the person who did the commit, the exact date and time of the commit, and the comment they provided. The information provided by log entries can be very helpful when attempting to solve mistakes and errors. For example, it is possible to see the exact changes that were made between one revision and another in a particular file. Simply enter svn diff -r followed by the range of revisions (x:y) and the file name. For example, svn diff -r 1276:1279 PERS1.xml will return log entries for revisions to PERS1.xml numbered 1276 through to 1279.

Commands

The following is a table of common commands used when working with SVN. Each command should be followed by pressing the Enter/Return key (⏎). Note that this includes regular (non-svn) terminal commands, and that some things differ between operating systems (the folder delimiter on Windows is a backslash (\), whereas it is a forward slash on Mac and Linux, for example).
Action How to do it
Open a terminal
  • Linux: Control + Alt + T
  • Mac: Command (⌘) + Space, then type terminal and press return
  • Windows: Windows key, r, type cmd and press return
Create a new directory mkdir moeml
Move into that directory cd moeml
Check out the repository (data folder only) svn checkout https://hcmc.uvic.ca/svn/london/db/data .
Check out the entire repository (takes a lot of disk space) svn checkout https://hcmc.uvic.ca/svn/london/ .
Where am I now? (What is the path to the current folder at the command line, also known as the working directory?) Mac & Linux: pwd
Windows: echo %cd%
List contents of current folder Mac & Linux: ls
Windows: dir /B
List contents of current folder with details Mac & Linux: ls -al
Windows: dir
Move into the stuff folder cd stuff
Move back up the tree (i.e. go to the containing folder) cd ../
Find out about the repo (must be run when your working directory is part of an svn repository checkout) svn info
Find out the svn revision history svn log
Show the last 5 log entries from the svn revision history svn log -l 5
Get detailed history svn log -v
Get history of one file (stuff/poem.txt) svn log -v path/to/file.txt
Path completion saves you typing a long file or folder name. You can type just enough to create a unique path, then press tab. ssvn log -v path/to/f then press TAB
Find all commits in a specific date range: svn log -r{2021-05-19}:{2021-06-02}
Find all commits by a specific user: svn log --search netlinkid
Find all commits in a specific date range by a specific user: svn log -r{2021-05-19}:{2021-06-02} --search netlinkid
Examining changes (from revision 3 to revision 4) svn diff -r 3:4 stuff/poem.txt
Catching the criminal1 svn blame stuff/poem.txt
Check the status of your repository (what has changed, what has yet to be added, et cetera) svn status
Add your new file (located at stuff/myfile.xml). A new file must be added before it can be committed. svn add stuff/myfile.xml
Commit all modified files svn commit -m "Adding my poem"
Commit just one file svn commit stuff/mypoem.xml -m "Adding @rhyme to all linegroup element"
Commit a sequence of files svn commit myFile.txt stuff/mypoem.xml bibliography.xml -m "Fixing references in myFile and mypoem and adding citations to the bibliography."

Further Information

For further information about how to use Subversion, consult Collins-Sussman, Fitzpatrick, and Pilato (2008).

Notes

  1. This could be also called Praising the encoder as svn praise performs the same action as svn blame. (MDH)↑

References

  • Citation

    Collins-Sussman, Ben, Brian W. Fitzpatrick, and C. Michael Pilato. Version Control with Subversion. Sebastopol: O’Reilly Media, 2008. Print.

    This item is cited in the following documents:

Cite this page

MLA citation

Holmes, Martin D., Tye Landels-Gruenewald, and Cameron Butt. Access Files from the Subversion Repository. The Map of Early Modern London, Edition 7.0, edited by Janelle Jenstad, U of Victoria, 05 May 2022, mapoflondon.uvic.ca/edition/7.0/subversion.htm.

Chicago citation

Holmes, Martin D., Tye Landels-Gruenewald, and Cameron Butt. Access Files from the Subversion Repository. The Map of Early Modern London, Edition 7.0. Ed. Janelle Jenstad. Victoria: University of Victoria. Accessed May 05, 2022. mapoflondon.uvic.ca/edition/7.0/subversion.htm.

APA citation

Holmes, M. D., Landels-Gruenewald, T., & Butt, C. 2022. Access Files from the Subversion Repository. In J. Jenstad (Ed), The Map of Early Modern London (Edition 7.0). Victoria: University of Victoria. Retrieved from https://mapoflondon.uvic.ca/editions/7.0/subversion.htm.

RIS file (for RefMan, RefWorks, EndNote etc.)

Provider: University of Victoria
Database: The Map of Early Modern London
Content: text/plain; charset="utf-8"

TY  - ELEC
A1  - Holmes, Martin
A1  - Landels-Gruenewald, Tye
A1  - Butt, Cameron
ED  - Jenstad, Janelle
T1  - Access Files from the Subversion Repository
T2  - The Map of Early Modern London
ET  - 7.0
PY  - 2022
DA  - 2022/05/05
CY  - Victoria
PB  - University of Victoria
LA  - English
UR  - https://mapoflondon.uvic.ca/edition/7.0/subversion.htm
UR  - https://mapoflondon.uvic.ca/edition/7.0/xml/standalone/subversion.xml
ER  -

TEI citation

<bibl type="mla"><author><name ref="#HOLM3"><surname>Holmes</surname>, <forename>Martin</forename> <forename>D.</forename></name></author>, <author><name ref="#LAND2"><forename>Tye</forename> <surname>Landels-Gruenewald</surname></name></author>, and <author><name ref="#BUTT1"><forename>Cameron</forename> <surname>Butt</surname></name></author>. <title level="a">Access Files from the Subversion Repository</title>. <title level="m">The Map of Early Modern London</title>, Edition <edition>7.0</edition>, edited by <editor><name ref="#JENS1"><forename>Janelle</forename> <surname>Jenstad</surname></name></editor>, <publisher>U of Victoria</publisher>, <date when="2022-05-05">05 May 2022</date>, <ref target="https://mapoflondon.uvic.ca/edition/7.0/subversion.htm">mapoflondon.uvic.ca/edition/7.0/subversion.htm</ref>.</bibl>

Personography