Subversion is an open source version control system, currently maintained by the Apache Software Foundation. Subversion is a centralized version control system, meaning that the repositories exist on a central server. With Subversion, you check out a working copy of the repository, do your work, and then commit your changes back to the repository. A Subversion working copy does not contain the entire history of the project, just the files for the working copy itself.
Subversion has been in use since 2000, and there is a very large amount of information and documentation available for it. If you need more information than what is provided in this user guide, you are strongly encouraged to seek out and find these resources.
The official documentation for Subversion is available for free online - http://svnbook.red-bean.com/. You can view this online, or download a PDF. You can also buy the book that the online documentation is based on - Version Control with Subversion
What is covered in this User Guide
Installing Subversion
Configuring Subversion on the Virtual Server
Create the svn file
Create the Subversion root directory
Testing Subversion
Creating the Subversion repos on the Virtual Server
Configuring access to the Subversion repos - svn, svn+ssh, http
Configuring svn access
Configuring svn+ssh access
Configuring http access
Subversion Quick Start
Quick Start - Command Line (Mac OS X/Linux/UNIX)
Quick Start - Windows and TortoiseSVN
Subversion is highly complex software, and there are a large number of options and possibilities for using it. This user guide is only able to cover the basics of using Subversion.
This user guide will cover:
How to install and configure Subversion on your Virtual Server
How to create a repo on the Virtual Server and configure access to that repo (svn, svn+ssh, http)
How to access a Subversion repo using the command line (Mac OS X/Linux/UNIX) or the Windows TortoiseSVN application
More complex scenarios, including advanced day to day usage of Subversion such as branching, merging, and tagging, are far outside the scope of this user guide. Please see the available Subversion documentation for more information.
If you are using the ISPmanager Control Panel, you can install Subversion from that Control Panel.
For ISPmanager 4, go to Server Settings > Applications. Install Subversion. More information on installing applications can be found here - Installing Server Applications.
For ISPmanager 5, go to Settings > Features. Install Subversion. More information on installing applications can be found here - Installing Features (Server Applications).
Information on how to tell which version of ISPmanager you are using can be found here - ISPmanager versions
After Subversion is installed, you will need to connect to the Virtual Server via SSH, and work from the command line. You will need to be able to work as the root user, and be able to navigate the Linux filesystem, execute basic commands, and edit files in a text editor (vim is available by default).
If you need to have Subversion set up, but are not able to do the required work from the command line, please contact eApps Sales to discuss having this done for you as a billable service.
Once you are connected to the VS, you will need to create a file in /etc/xinetd.d to control the svn service, and restart the xinetd service. Then you will need to create the root directory for the Subversion repositories, and then test that the svn service is responding correctly.
Change directories to /etc/xinetd.d, and create a file called svn using the vim svn command. This creates the file, and opens it for editing.
[root@eapps-example ~]# cd /etc/xinetd.d
[root@eapps-example xinetd.d]# vim svn
Copy and paste this into the svn file, making sure to get the syntax and formatting correct. Note which lines are commented out.
# default: on
# Subversion server
service svn
{
socket_type = stream
protocol = tcp
user = root
wait = no
disable = no
server = /usr/bin/svnserve
server_args = -i --root=/opt/svnserve
#port = 3690
}
Once you have created the file and added the content, save and exit the file, and restart the xinetd service.
For CentOS 6, use the service xinetd restart command:
[root@eapps-example xinetd.d]# service xinetd restart
For CentOS 7, use the systemctl restart xinetd command:
[root@eapps-example xinetd.d]# systemctl restart xinetd
The Subversion repositories will reside in /opt/svnserve. This directory does not currently exist, so you will have to create it. Change directories to /opt, and use the mkdir svnserve command to create the directory.
[root@eapps-example ~]# cd /opt/
[root@eapps-example opt]# mkdir svnserve
To test that Subversion is responding properly, you will need to telnet to the port that it runs on, port 3690. You need to test this both internally (from the VS) and externally (from the command line or DOS prompt of your local computer).
To test internally, use the telnet localhost 3690 command. This will try to connect to that port from the local connection.
[root@eapps-example ~]# telnet localhost 3690
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
( success ( 2 2 ( ) ( edit-pipeline svndiff1 absent-entries commit-revprops depth log-revprops partial-replay ) ) )
Press enter to get back to the command line.
If you get a Connection refused error, go back and verify the /etc/xinetd.d/svn file you created, and also restart the xinetd service. If you still cannot connect to the port internally, make sure that you do not have any iptables rules blocking the connection. If you are still having issues, contact eApps Support.
To test the connection externally, which is necessary if you will be connecting to the Subversion repos on the VS from your local computer, use a similar command, but substitute localhost for the hostname or IP address of your Virtual Server. This command is run from either the terminal or console of a Mac OS X/Linux/UNIX system, or from the command prompt on a Windows system.
This example uses eapps-example.com, make sure to substitute your own hostname or IP address.
local-computer:~$ telnet eapps-example.com 3690
Trying 68.169.60.79...
Connected to eapps-example.com.
Escape character is '^]'.
( success ( 2 2 ( ) ( edit-pipeline svndiff1 absent-entries commit-revprops depth log-revprops partial-replay ) ) )
Press enter to get back to the command prompt or command line.
If your internal test passed, this test should pass also. If you get a Connection refused error, you may be running up against a local router or firewall configuration, or possibly a port block at the ISP level. Contact the person responsible for your local network if you need assistance troubleshooting the issue. You may need to call your ISP for assistance if it appears that the port is blocked on their end.
All the Subversion repositories will live under the Subversion root directory of /opt/svnserve. To create a repo, change directories to /opt/svnserve and use the svnadmin create repo_name command. For the name of the repository, choose a name that is meaningful to your project. Make sure the name is all one word - do not use spaces in the name. You can use underscores.
Also, be aware that the names are case sensitive. You can use capital letters in the name, but keep in mind that to Linux, repo_name, REPO_NAME, and Repo_Name are all completely different files. You will need to make sure that you use the exact same name in your Subversion client that you use to name the repo.
[root@eapps-example ~]# cd /opt/svnserve
[root@eapps-example svnserve]# svnadmin create example_repo
When you create the repo with svnadmin create repo_name, this puts the files and directory structure required by Subversion under the repository directory. You can change directories to the repo itself and see this.
[root@eapps-example svnserve]# cd example_repo/
[root@eapps-example example_repo]# ll
total 24
drwxr-xr-x 2 root root 4096 Jul 16 08:15 conf
drwxr-sr-x 6 root root 4096 Jul 16 08:15 db
-r--r--r-- 1 root root 2 Jul 16 08:15 format
drwxr-xr-x 2 root root 4096 Jul 16 08:15 hooks
drwxr-xr-x 2 root root 4096 Jul 16 08:15 locks
-rw-r--r-- 1 root root 229 Jul 16 08:15 README.txt
To create additional repositories, run the svnadmin create repo_name command again from the /opt/svnserve directory.
There are three main methods of access to a Subversion repo:
svn - this is the standard method of access to Subversion, and is controlled directly by the Subversion (svn) protocol. svn access can be done either from the command line or from a Subversion client such as TortoiseSVN.
svn+ssh - to use svn+ssh, each user will need to have SSH access to the Virtual Server, and you will need to change the owner and group of the Subversion repo to allow this. Access control is done through SSH, not through Subversion. svn+ssh access is generally done directly from the command line, but it can be configured through a Subversion client like TortoiseSVN. Please consult the documentation for your Subversion client if you want to set up svn+ssh access through it.
http - to use http access to Subversion, you will need to install and configure the mod_dav_svn module. This will allow you to connect to Subversion using the http protocol. Access control is done through HTTP, not through Subversion. This method is mostly used in environments where only http access is allowed. Most Subversion clients, such as TortoiseSVN, can use http access.
Which method of access you choose will depend on your particular circumstances. eApps does not recommend one method over another.
Using the svn protocol, you can configure access to your Subversion repos. Access is configured on a per-repo basis, meaning that users who have access to (for example) project1_repo do not have access to project2_repo, and vice versa, unless you have specifically added the uses to both repos.
 |
Be aware that this only controls access if you are using the svn connection method. If you are using svn+ssh or http, then any configuration shown here will be ignored. |
The access control for each repo is configured inside the repo directory, from the command line. Connect to the Virtual Server using SSH, and as the root user, change to the /opt/svnserve/repo_name directory. This user guide uses example_repo, make sure to substitute your own repo name.
Once you have changed directories to the repo, list the contents.
[root@eapps-example ~]# cd /opt/svnserve/example_repo
[root@eapps-example example_repo]# ll
total 24
drwxr-xr-x 2 root root 4096 Jul 16 08:15 conf
drwxr-sr-x 6 root root 4096 Jul 16 08:15 db
-r--r--r-- 1 root root 2 Jul 16 08:15 format
drwxr-xr-x 2 root root 4096 Jul 16 08:15 hooks
drwxr-xr-x 2 root root 4096 Jul 16 08:15 locks
-rw-r--r-- 1 root root 229 Jul 16 08:15 README.txt
[root@eapps-example example_repo]#
Now change directories to the conf directory. This is where the the access control for svn is managed. There are three files in this directory: authz, passwd, and svnserve.conf. You will need to edit the svnserve.conf and passwd files.
[root@eapps-example example_repo]# cd conf
[root@eapps-example conf]# ll
total 12
-rw-r--r-- 1 root root 1080 Jul 16 08:15 authz
-rw-r--r-- 1 root root 309 Jul 16 08:15 passwd
-rw-r--r-- 1 root root 2279 Jul 16 08:15 svnserve.conf
[root@eapps-example conf]#
The first file to edit is the svnserve.conf file. This file tells the svn protocol which file to use to allow access to the repo. Open the file in a text editor (vim is available by default), and uncomment line 20: password-db = passwd
Once you have done that, save and exit the file. There are more advanced configuration options available in the svnserve.conf file, please see the official Subversion documentation for more information.
Once you have edited svnserve.conf, edit the passwd file. This is where you add the users who will be able to access the Subversion repos using the svn protocol, and their passwords.
The default file looks like this:
### This file is an example password file for svnserve.
### Its format is similar to that of svnserve.conf. As shown in the
### example below it contains one section labelled [users].
### The name and password for each user follow, one account per line.
[users]
# harry = harryssecret
# sally = sallyssecret
Add your users to this file, one user per line, in the same format as shown by the two example users, but make sure your users are not commented out. Choose strong passwords for the users.
### This file is an example password file for svnserve.
### Its format is similar to that of svnserve.conf. As shown in the
### example below it contains one section labelled [users].
### The name and password for each user follow, one account per line.
[users]
# harry = harryssecret
# sally = sallyssecret
svnuser1 = Gt93jqlt
svnuser2 = DJEj2s8e
At this point, your users can now access the Subversion repo using the svn connection method with the usernames and passwords that you have created. They can access the repo using the command line or from a Subversion client such as TortoiseSVN.
You can configure access to your Subversion repos using svn+ssh, which is where you tunnel the svn connection through ssh. This type of configuration is generally for advanced users who are already very familiar with the Linux filesystem and manipulating users, groups, and permissions.
To configure this setup, you will need to make changes to the user and group for your Subversion repo, and you will need to grant your users SSH access to the Virtual Server.
Generally, to configure svn+ssh access, you will need to:
Create the users on the VS, and make sure they have shell/SSH access to the VS
Create a group for the users that will be using Subversion, and add those users to the group
Change the owner/group/permissions for the Subversion repo that these users are going to use
A scenario using svn+ssh can become quite complex, which is why it is recommended for advanced users who are already familiar with implementing the configuration listed above. If you wish to implement an svn+ssh scenario but do not have the required Linux skills, please contact eApps Sales to discuss having this done for you as a billable service.
The official Subversion documentation has some information on setting up svn+ssh, and there are also other resources available online that document various ways to set this up.
You can access your Subversion repos using http. To do this, you will need to install the mod_dav_svn module. When installed, this module creates a subversion.conf file that you will need to edit to allow http access to your repos. Then you will need to create a user and password that is managed by http in order to access the repos.
The mod_dav_svn Apache module is installed from the command line, using yum. Log in to the Virtual Server using SSH, and as the root user, run the command yum install -y mod_dav_svn
[root@eapps-example ~]# yum install -y mod_dav_svn
After the module installs, change directories to /etc/httpd/conf.d, where there is now a subversion.conf file. You will need to edit the subversion.conf file to allow http access to your repos.
To do this, you will need to add a section to the end of the file, with the path to the repo, and the path to the file that manages the users and passwords needed to access the repo. This section is called a Location block, and you will have to have one Location block per repo.
The default Location block looks like this:
<Location /repository_name>
DAV svn
SVNPath /opt/svnserve/repository_name
AuthType Basic
AuthName "Example Repo"
AuthUserFile /etc/subversion/svn-passwd-file
Require valid-user
</Location>
Set the values for repository_name and AuthName to the name of the Subversion repo. Note that repository_name appears twice in the file. The AuthUserFile is the location where the user names and passwords for the users who can access the Subversion repo using http will be configured.
Here is an example of a working Location block in the subversion.conf file. This uses example_repo as the repository_name. Remember that these blocks go at the end of the subversion.conf file, and that there must be one Location block per repo.
<Location /example_repo>
DAV svn
SVNPath /opt/svnserve/example_repo
AuthType Basic
AuthName "Example Repository"
AuthUserFile /etc/subversion/svn-passwd-file
Require valid-user
</Location>
Once you have added the Location blocks for your repos to subversion.conf, restart httpd.
For CentOS 6, use the service httpd restart command:
[root@eapps-example conf.d]# service httpd restart
For CentOS 7, use the systemctl restart httpd command:
[root@eapps-example conf.d]# systemctl restart httpd
The Location blocks in subverion.conf are set to Require valid-user. This means that only someone who has a valid username and password in the svn-passwd-file can connect to the repos.
To create the usernames and passwords, you will need to use the htpasswd command, which you will supply with a username and it will prompt you for a password. The htpasswd command encrypts the passwords using MD5, so that they are not viewable as plain text.
 |
Please pay careful attention to the switches for the htpasswd command. The first command shown will create the svn-passwd-file, and then add the user to it. The next command shown will append a new user to the existing file. If you run the first command again for any subsequent user, you will wipe out the existing file and any users added to it. |
Change directories to /etc/subversion, and run the htpasswd -cm svn-passwd-file username command, where username is the name of the user that will be connecting to the Subversion repo using http. The username should be in lowercase letters, with no spaces. Usernames are generally between 6 and 8 characters long, but can be longer. This example uses svnuser1.
[root@eapps-example ~]# cd /etc/subversion
[root@eapps-example subversion]# htpasswd -cm svn-passwd-file svnuser1
New password:
Re-type new password:
Adding password for user svnuser1
[root@eapps-example subversion]# cat svn-passwd-file
svnuser1:$apr1$OedENX9L$K0tMD2v5hWKVIiGQJY0/B0
[root@eapps-example subversion]#
To add any additional users to the svn-passwd-file, use the htpasswd -m svn-passwd-file username command. Note that the switch is now -m, instead of -cm. If you use the -cm switch again, you will overwrite the existing file.
[root@eapps-example subversion]# htpasswd -m svn-passwd-file svnuser2
New password:
Re-type new password:
Adding password for user svnuser2
[root@eapps-example subversion]# cat svn-passwd-file
svnuser1:$apr1$OedENX9L$K0tMD2v5hWKVIiGQJY0/B0
svnuser2:$apr1$OwOqA6Sr$FCvv.QG/rerqvbmqQG6IO1
[root@eapps-example subversion]#
Once your users have been added, they will then be able to access the Subversion repos using http. This is usually done via a Subversion client, but can also be done via a web browser.
The following will walk you through importing files from your local computer into a Subversion repo on the Virtual Server, checking those files out of the repo, and then committing your changes back to the repo.
There are two Quick Start examples here - one using the command line on Mac OS X or Linux/UNIX, and one using TortoiseSVN on Windows.
If you are using Mac OS X or Linux/UNIX, you may need to install Subversion on your local computer. Downloads are available here - http://subversion.apache.org/packages.html. Please note that installing and configuring Subversion on your local computer is outside the scope of this user guide and outside the scope of eApps support.
For Windows, you will need to install a Subversion client such as TortoiseSVN - http://tortoisesvn.net/. There are other Subversion clients available for Windows, but TortoiseSVN is both free and open source, and very widely used. All the examples for Windows in this Quick Start will use TortoiseSVN. If you are using a different Windows SVN client, you will need to consult the documentation for that client for information. Please note that installing and configuring TortoiseSVN or any other Subversion client on your local computer is outside the scope of this user guide and outside the scope of eApps support.
|
Neither of these examples is meant to be a comprehensive guide to using Subversion, they are simply a quick overview of a common Subversion workflow. |
This example will walk you through importing files to the Subversion repo on your Virtual Server, checking those files out, and committing your changes back to the repo.
In this example the files are in a directory called project_folder, and the Subversion repo is called example_repo on the eapps-example.com Virtual Server. The project itself will be called example_project. Please substitute your own files, repo name, project name, and Virtual Server name.
Change directories to the location of your project files. All the files will need to be in one directory, which can have subdirectories. Run the following command: svn import -m “Import message” svn://hostname/repo_name/project_name
For this example, the command would be svn import -m "Initial import" svn://eapps-example.com/example_repo/example_project
Make sure the command is all on one line.
-localcomputer:~ user$ cd project_folder
-localcomputer:project_folder user$ svn import -m "Initial import" svn://eapps-example.com/example_repo/example_project
Authentication realm: <svn://eapps-example.com:3690> d0b2310d-dad0-4364-af7f-5c556ab7ab93
Password for 'user':
Authentication realm: <svn://eapps-example.com:3690> d0b2310d-dad0-4364-af7f-5c556ab7ab93
Username: svnuser1
Password for 'svnuser1':
Adding file3.c
Adding file2.html
Adding file4.h
Adding file1.txt
Committed revision 1.
-localcomputer:project_folder user$
There are several things to be aware of here:
The first authentication attempt will try to use your username on the local computer: press Enter
On the second authentication attempt, enter the name of the user that you created in /conf/passwd in the repo, and then the password for that user
Your files have now been imported to the example_repo on the VS.
To check out the files from the Subversion repo, change to or create a directory where you will check out the files, and run this command: svn co svn://hostname/repo_name/project_name (make sure the command is on one line).
This command will check the files out to a directory called project_name on your local computer, so make sure that this directory does not exist in the location where you will be checking the files out. Since the project was imported to example_project, that will be the name of the directory created.
For this example, the command would be svn co svn://eapps-example.com/example_repo/example_project
-localcomputer:~ user$ svn co svn://eapps-example.com/example_repo/example_project
A example_project/file3.c
A example_project/file2.html
A example_project/file4.h
A example_project/file1.txt
Checked out revision 1.
-localcomputer:~ user$ cd example_project/
-localcomputer:example_project user$ ls
total 56
file1.txt
file2.html
file3.c
file4.h
-localcomputer:example_project user$
Notice that no username or password was requested. This is because in the conf/svnserve.conf file, anon-access = read is the default. So anyone can checkout (read) the files, but only authenticated users can make any changes to the repo, such as importing files.
If you want to change this, uncomment the # anon-access = read line in the /opt/svnserve/repo_name/conf/svnserve.conf file, and change “read” to “none”, and restart xinetd. This will stop unauthenticated users from being able to check out any files from this repo.
If you uncomment the anon-access line and change the value to none, you will see something similar to this when you try to check out a repo:
-localcomputer:~ user$ svn co svn://eapps-example.com/example_repo/example_project
Authentication realm: <svn://eapps-example.com:3690> d0b2310d-dad0-4364-af7f-5c556ab7ab93
Password for 'user':
Authentication realm: <svn://eapps-example.com:3690> d0b2310d-dad0-4364-af7f-5c556ab7ab93
Username: svnuser1
Password for 'svnuser1':
A example_project/file3.c
A example_project/file2.html
A example_project/file4.h
A example_project/file1.txt
Checked out revision 1.
-localcomputer:~ user$
Again, there are several things to be aware of here:
The first authentication attempt will try to use your username on the local computer: press Enter
On the second authentication attempt, enter the name of the user that you created in /conf/passwd in the repo, and then the password for that user
Once you have made your changes to your files, you can commit them back to the repo. Do this with the svn commit -m "Commit message" command. In the Commit message, enter in what files you changed and what you changed.
For this example, the command would svn commit -m "Changed files"
-localcomputer:example_project user$ svn commit -m "Changed files"
Sending file1.txt
Sending file4.h
Transmitting file data ..
Committed revision 2.
-localcomputer:example_project user$
Notice that no username or password was requested. This is because svn on your local computer remembers your username and password from when you imported or checked out the files, and uses that to commit the files. In the conf/svnserve.conf file, the default is auth-access = write, meaning that only an authenticated user can write (commit) to the repo.
This example will walk you through importing files to the Subversion repo on your Virtual Server, checking those files out, and committing your changes back to the repo.
These examples use TortoiseSVN and Windows 7. While some minor specifics may be slightly different, these steps should work generally the same for any recent version of Windows and TortoiseSVN.
You can download TortoiseSVN from here - http://tortoisesvn.net/downloads.html. TortoiseSVN is free and open source.
Please note that the installation, configuration, and general usage of TortoiseSVN is outside the scope of eApps support. TortoiseSVN is well documented and has an active user community that you can turn to if you need answers to specific questions - http://tortoisesvn.net/support.html
In this example the files are in a folder called ProjectFolder, and the Subversion repo is called example_repo on the eapps-example.com Virtual Server. Please substitute your own files, repo name, project name, and Virtual Server name.
Navigate to the parent folder where the folder holding your project files (ProjectFolder) is located. Right click on this folder, navigate to TortoiseSVN, and then to Import.
This opens the Import dialog box.
URL of repository - depending on which method of access you have set up (svn or http), enter the URL of the Subversion repo here. This example uses svn, so the URL is svn://eapps-example.com/example_repo. If this example was using http, the URL would be http://eapps-example.com/example_repo
Import message - enter in the import message here
Once you have entered the information, click OK
This opens the Authentication dialog box.
Username - make sure to use the correct username that matches your authentication method - either svn or http
Password - use the correct password for your username
Once you have entered your Username and Password, click OK.
This will import the files into the Subversion repo.
Click OK to finish the import process.
In this example, you are going to check out the files from the Subversion repo into a folder called RepoFolder. Make sure to substitute your actual folder name where appropriate.
Navigate to the parent folder of RepoFolder. Right click on RepoFolder, and click on SVN Checkout
This will open the Checkout dialog box.
Repository
URL of repository - enter the URL of the Subversion repo. This will usually default to the URL of the last repo used
Checkout directory - this will be the full path to the folder where you will check out the repo
Checkout Depth - leave at the default of Fully recursive unless you have a very specific need to change this
Revision - set to HEAD revision by default, you can check out another revision if needed
To checkout the files, click OK
The progress is shown in the Checkout Finished dialog box.
Click OK
Notice that the folder where you checked out the files to now has a green check mark.
This means that the folder is under version control, and is current. Once any changes to the folder are made, the green check will turn into a red exclamation point.
Also notice that the files in the folder have green check marks, for the same reason - they are under version control and current.
After you have made your changes to the files, you can commit them back to the Subversion repo.
The files that have been changed will now have a red exclamation point instead of a green check. This tells you that the contents of the files have been changed, and these changes need to be committed back to version control.
To commit the files back to the Subversion repo, change back to the parent folder. You will see that the folder that contains the project files also has a red exclamation point, showing that the files inside it have been changed, and those changes need to be committed to version control.
Right click on the folder, and click on SVN Commit.
This opens the Commit dialog box.
Click OK to commit the changes to the Subversion repo.
You may be asked to authenticate in order to commit your changes. If so, enter in the correct username and password.
Once the commit completes, you will see the Commit Finished dialog box.
Click OK. You will now see that the folder has a green check mark again, as do the files in the folder. This means that the files are under version control, and current.
