Subversion, often abbreviated SVN, is a software versioning and revision control system. Subversion is used to maintain current and historical versions of files such as source code, web pages, and documentation. The purpose of this Subversion (SVN) tutorial is to walk through the basics of SVN usage.
For those of you who do not know anything about version control systems, do read the introduction to version control systems chapter, but if you already know what version control systems are, you may skip the introduction and jump right into the SVN Environment setup. If you are already familiar with Subversion, you can pick a topic of interest from the table of contents below.
Version control systems record and store changes, so you can revert to a specific change point in history. You can think version control system like a saving mechanism found in video games, with the added benefit of collaborating with others. Version control systems in software development fall into two categories:
Both distributed and centralized version control systems have benefits and downfalls that make them ideal for different domains and situations. The most popular open source version control systems are Git, Subversion (SVN), and Mercurial (HG), where Git and Mercurial represent distributed version control systems and Subversion centralized version control system. This tutorial walks you through the basics of Subversion (SVN) usage.
Before you dive into the commands and actual usage, let's cover some basic terminology. If you feel comfortable on the basics, you can skip this section by jumping right into the environment setup.
A repository is where the code and its history is stored. The repository can be accessed through various ways depending on the server where it's hosted. At least filesystem, SSH and HTTP(S) based access methods are commonly used. In centralized version control systems, such as SVN, there's always one central repository and one to many local checkouts, typically on user machines. Files can be modified simultaneously within the local checkouts and the changes can be contributed to the central repository, when they are ready.
SVN server is the place where the repositories are hosted. As there are probably many projects in a company, similarly there can be multiple repositories. It's typical to use a server software, such as Deveo to create and manage the repositories in projects, but SVN also includes a built-in tool, called svnserve, that can be used to host a repository. The benefits of using a more advanced SVN server, such as Deveo, are that you get a graphical user interface, access management, integrations to third party tools and more.
If you don't want to setup and maintain an SVN server yourself, you can use the generally available SVN hosting services. SVN hosting allows you to create a repository in the cloud, manage its access rights, and do nearly everything you could do with your own SVN server, but without the management and maintenance overhead. SVN hosting is nowadays becoming more and more popular even for companies that have had a self-hosted SVN server.
Commits represent a saved state of the code at a certain point in time. Doing a commit is literally the same thing as saving the state in a video game. Commits in SVN are done between the local checkout and the central repository. The changes that are committed are transferred to the central repository. A commit includes both the changes, and a commit message. The commit message explains in detail what changes you are introducing. It's important to use meaningful commit messages, so that others who you are contributing with, understand your changes in addition that you find the changes you have done later on.
The working copy represents the changes that are on your local checkout and that are not yet committed. The working copy could be called a private sandbox where you can play around freely. Only when you want to publish something to others, you make a commit.
Branches are used when you are working multiple things in parallel. Branches allow you to keep multiple diverge copies of your work. An example would be that you want to develop two features at a time. You create two branches and develop each feature in its own branch. Finally, when the feature is ready, you unite the branch where you were developing it to the main branch. The main branch in SVN is called `trunk` but more of that later. In SVN branches are actually only copies of a directory, and thus, it's common to use only one branch when developing.
Tags allow you to label a certain point in history. In SVN a tag is merely a copy of the directory similar to a branch. Tags are used to mark releases or other larger change points in the version history. Tags are easier to find than commits, as they stand out on their own directories, similarly as branches. Adding changes on top of a tag is generally discouraged practice, can be used for example in releasing bug fixes to major versions of a software.
In order to start working with SVN, you need two things: SVN client and SVN server or SVN hosting provider. In this tutorial, you are going to use Deveo as your SVN hosting provider in order to skip the hassle related to setting up and managing the SVN server. Deveo offers free Git, Subversion (SVN) and Mercurial (HG) repository hosting with no user or repository limits.
Start off by creating an account in Deveo. If you are using another SVN hosting provider or have set-up SVN server on your own, you can skip this part. For those of you who wish to host SVN repositories with the least amount of worrying, head down to https://deveo.com/signup and create your account. You should receive an email after which you can login to your account.
When logged in to Deveo, you can create a new project through the top-right side of the user interface by clicking the icon with a `+` on it. After you have named and created your project, you can create a new repository from the same `+` icon.
After you have an SVN repository set up, you also need to install an SVN client. The official home page of apache Subversion has listed the packages for each operating system. In this tutorial, you are going to use the command line client so that you will understand the basic concepts. Later on, you can use SVN client with a graphical user interface to accomplish the same things and more. To get more information on different clients available, you can read Deveo list of SVN clients.
The basic lifecycle using Subversion (SVN) for your development consists of x parts:
You will learn each part of the lifecycle in the following chapters.
The first thing you need to do is to checkout a repository. SVN checkout will transfer the revision of your choice of a given repository and initializes it as your working copy. As you have just created the repository, there are no commits made to that repository, and thus, the repository contains no revisions. In this case, an empty workspace is checked out instead. You can go ahead and execute to following command in a directory of your choice:
svn checkout https://app.deveo.com/<COMPANY>/projects/<PROJECT>/repositories/subversion/
In the case of Deveo, you can copy the checkout URL from the Web UI. The first time you do a checkout, the SVN command line client might ask you to accept a certificate from the server. In this case, select to permanently trust the certificate. You might have to rerun the checkout command again.
During the checkout, the SVN command line client asks for a username and password. If you signed up to Deveo, the username is in the form of `youremaildomaincom`, and can be found on your user profile. The password is what you specified during the signup process. Note that you are using HTTPS protocol to communicate with the repository. If you are using another code hosting solution or have setup the SVN server yourself, use the credentials and checkout URL specified in the appropriate instructions.
After the svn checkout command has executed successfully, you should see the following message:
Checked out revision 0.
SVN has a running revision number. As you checked out an empty repository, the revision number is 0. If the command was executed successfully you should see a directory with the name of the repository in the directory you currently are. Go into the directory with cd
Path: Working Copy Root Path: /Users/<USER>/Documents/Projects/<REPOSITORY-NAME> URL: https://app.deveo.com/<COMPANY>/projects/<PROJECT-NAME>/repositories/subversion/<REPOSITORY-NAME> Relative URL: ^/ Repository Root: https://app.deveo.com/<COMPANY>/projects/<PROJECT-NAME>/repositories/subversion/<REPOSITORY-NAME> Repository UUID: fbd5283e-fa8a-11e6-8cbc-3bf3066f8f41 Revision: 0 Node Kind: directory Schedule: normal Last Changed Rev: 0 Last Changed Date: 2017-02-24 14:15:51 +0200 (Fri, 24 Feb 2017)
The output might differ depending on whether you are using your own SVN server or an SVN hosting platform, such as Deveo.
After you have checked out the repository you can start using it. As you are already inside the repository, create a text file inside the directory using your favorite editor, such as vim, nano or Notepad. You can also create an empty text file using the following command:
After you have created the text file, you can type svn status, and notice that it lists the file you just created with a preceding question mark. The question mark (?) represents that the file is not yet under version control. You can add files to be tracked by svn using the svn add command. Go ahead and add the freshly created text file to be versioned using SVN with the following command:
svn add text-file.txt
The svn add command should give you a following output if the file was successfully added.
You can also check that the file was added to be versioned with the svn status command. It should show you the exactly same output. In order to do changes, open the file with your favourite text editor, add some text to the file, save the file and exit your editor. Lastly, in order to create a new revision, you can commit the changes using the following command:
svn commit --message "<YOUR COMMIT MESSAGE HERE>"
Replace the <YOUR COMMIT MESSAGE HERE> part with an explanation of what you did. It will be stored alongside with your changes to the file. Congratulations, you have now made your first commit. If you are using Deveo for SVN hosting, you can go to the web UI and see that the changes are shown there. The online code browser is one of the benefits of using an SVN hosting provider or a more sophisticated SVN server. You can verify that the changes were successfully submitted to the server by executing the svn status command. If you did not do any changes after the commit, there should be no output.
Let's continue the tutorial by diving into how you can review changes between different revisions. Let's continue to work on your existing repository. As you are already familiar with the concept of adding new files to be versioned and committing the changes, add and commit two empty files to the repository. As a reminder, you can use the following commands to accomplish this:
touch foo.txt bar.txt svn add foo.txt bar.txt svn commit --message "Add two files."
Now your repository should contain three files total. You should also have two revisions in the repository. Before you go forward, let's learn one more command that is useful when you are working with others. This command is svn update. You need to run it before you can list the revisions in the repository using svn log command.
In addition to updating the working copy, svn update command brings changes from the repository into the working copy. While you could give svn update command a revision, which would allow us to move in time, it's more common use case to simply type svn update without additional arguments. This will bring your working copy up-to-date with the latest revision. As a trivia, the latest revision is also called the HEAD revision. This information will come handy later on. Run the following command to update your working copy up-to-date with the latest revision:
After successfully executing svn update command, the output should be as below:
Updating '.': At revision 2.
It's necessary to run the svn update command in order to list the revisions in the repository. In addition, if someone else has made modifications to the same files you are editing, SVN forces you to update the files before doing a commit. To continue, in order to list all of the revisions in the repository you are working with, run the following command:
Which will output us something like below:
------------------------------------------------------------------------ r2 |
If you wish to see what has changed between your working copy and previous revisions use svn diff command. Let's see it in action. Edit the two files foo.txt and bar.txt you created previously with your favorite text editor. Add some text lines to both, save the changes and finally, exit the editor. If you execute an svn status command, you should see that both of the files are prefixed with M, which marks for modified. In order to see the actual changes, rather than just a summary, execute the following command:
svn diff command is used to display local modifications in a working copy. In your case, you have modified two of the files, and the output of the diff command should look something like below:
Index: bar.txt =================================================================== --- bar.txt (revision 2) +++ bar.txt (working copy) @@ -0,0 +1,3 @@ +yksi +kaksi +kolme Index: foo.txt =================================================================== --- foo.txt (revision 2) +++ foo.txt (working copy) @@ -0,0 +1,3 @@ +line +two +three
If you are interested in changes between two arbitrary revisions, you can call the svn diff command with a revision or revisions. The following command, for example, shows the changes between the two revisions you have in your repository:
svn diff -r 1:2
As a conclusion, use svn status to show the overall view on your working copy, use svn log to show the list of commits in a repository and finally, use svn diff to show the changes between your working copy and the repository, or between any two arbitrary revisions. Finish off by committing your changes to the two files with the following command:
svn commit --message "Changes to two files."
Sometimes you might not be satisfied with the changes you have made and want to revert them. SVN provides a command to do just that. As a simple example, make changes to one of your files, but do not commit the changes. In order to revert or "clear" the changes, you can use the following command:
This will bring your file back to the state it was before your edits. You can revert not just single files, but directories or even the whole repository. Watch out, though, as the outcome is irreversible. You can test the revert command in action with the following commands after doing changes to one of your files:
svn status svn revert
The first execution of the svn status command should show that the file has changed. The second execution should not show the file that you just reverted.
If you wish to revert already committed changes you can use the svn merge command to achieve that. To revert the revision 3 in the repository you can use the following commands:
svn update svn merge -c -3 . svn commit --message "Reverted revision 3." The output of the aforementioned commands depends on the revision you are reverting. If There is a new file added in the revision you are reverting, the output might look something like below:
--- Reverse-merging r6 into '.': D file.txt --- Recording mergeinfo for reverse merge of r6 into '.': U . --- Eliding mergeinfo from '.': U .
After which running svn status should give a similar output as below:
When reverting a complete revision, you need to make a commit afterward. This will give you a chance to do extra modifications before submitting changes. When reverting another revision, bear in mind that the reverted revision is still there. What you are simply doing is a commit that is inverse to the original revision. When doing reverts for existing commits, there is a high chance that the revert causes a conflict that you need to manually resolve.
Sometimes when you are doing modifications to the same file with your fellow colleague you might even edit the same line. In this case, you will face a conflict. Conflicts are part of the daily workflow and solving them is fairly straightforward. In order for us to artificially cause a conflict, you need to checkout the repository into another directory. Open a new terminal, navigate to a directory that is outside of your repository and type the following command in order to checkout a new copy of your repository
svn checkout https://app.deveo.com/<COMPANY>/projects/<PROJECT>/repositories/subversion/<REPOSITORY>
If you are in the directory where your other repository already is, remember to add a distinguishable name after the checkout URL as a parameter to the checkout command. Like before, you obtain the repository URL from Deveo, if you are using it to host your repository. Go inside the checkout out repository directory, edit one text line in one of the files and commit the changes. Go back to the first checkout of the repository, edit the same file and change the same line but this time, make a different change.
When you try to commit the changes, your svn client should output something shown below:
svn: E155011: Commit failed (details follow): svn: E155011: File '/Users/<USER>/Documents/Projects/<REPO>/text-file.txt' is out of date svn: E160024: resource out of date; try updating
This means that you need to run svn update before you can commit. Run svn update, and notice that the svn command line client tells you that there's a conflict. There are various ways to solve the conflict. You are going to do it manually within our text editor. Enter `p` and press enter to continue. If you now type svn status, you should see that the file that you edited is prefixed with C status code, which represents a conflict. There are three other copies of the same file, prefixed with .mine, .rX and rY that represent the different revisions of the file. You don't need to care about them, and they are deleted after the conflict is resolved.
In order to solve the conflict, edit the conflicted file. You can see the file has the following markers from each revision included:
<<<<<<< .mine ||||||| .r3 ======= >>>>>>> .r5
The easiest way to solve a simple conflict is to remove the aforementioned conflict markers and rewrite the conflicted line in a correct form. Make the necessary edits, save the file and exit the editor.
Before you make a commit, SVN needs to know that you have resolved the conflict. Since you solved the conflict by editing the original file, mark the conflict as resolved with the following command:
svn resolve --accept=working text-file.txt
If you run the svn status command again, you should see that the previously conflicting file is now prefixed with the M status code, which represents a modified file. You can also notice that the three new files are also gone. Finish the conflict resolution by doing a commit.
This tutorial walked through the basics of SVN usage. You should be comfortable to work with the basic concepts and how to work with Subversion repository. If you wish to host your SVN Repositories either in the cloud or manage SVN repositories behind your company firewall, Deveo offers SVN hosting and can be installed as an SVN server behind your corporate firewall.
Sign up for free