SVN in 30 minutes

As always at the end of the page will find the LaTeX pdf version.

Before start just some notes: I decided to write a guide about SVN and not about GIT only because at work I use it. Since I wrote this document for the office I thought would have been good publish it even for others.
Personally I prefer GIT, in fact this is the reason why you’ll find all my source code on github.

Introduction

Every time you start to work on something, whatever it is, it is very useful use a Version Control System.
As you can see from the figure 1 a VCS allows you to manage your files keeping track of all changes (eventually between you and all other users), allowing you to move back and forward to marked points called commit.
A versioning software allows you also other operations like: branching, merging, adding external repositories, locking files, …

A complete version control system is divided in two parts:¹ the server and the client that are normally represented by two separate entities connected through a network connection.

The server is where all operations are executed and where the code within the database² is stored, this is why it must be absolutely reliable and guarantee complete data integrity.
The client is where all operations on files are managed and where files are normally used.

In this post I’m going to explain you how to use Apache Subversion, often simply abbreviated as SVN to maintain a project’s files under version control system.

I’ll guide you from the very beginning to the most used SVN functions.
In the next sections you’ll find how:

• create a repository;
• checkout a repository;
• add, commit, update and revert files;
• branch, merge code and resolve conflicts;
• tag software release;
• include externals;
• launch command from script;
• avoid common mistakes.

All examples use the local machine for both the server and client functionality, so there is no need to have another PC on the local network. Of course there is nothing to stop you to execute the server part on a real server machine.

Before start with the guide you will need to install the software if not already done.

Figure 1: Typical develompent work flow using a VCS.

Install the software

Download TortoiseSVN and install it including the command line client tools option (figure 2) to be able to run the SVN commands from scripts as well.

Figure 2: Install SVN command line client tool.

If everything has gone well you should have now the TortoiseSVN as a Windows shell extension (figure 3).

Figure 3: SVN Windows shell correctly installed.

Setup a project

To use a version control system on a project you need:

• a repository.
• a working folder.

Once you have these two, you can start to develop your project… Let’s see how to start.

The version control system is like a service that runs on an operating system, it is there, but you can’t “see it” until you execute a certain command. To interact with the server you have to send commands from the client using the command line, or a more simple, graphical interface.

In this tutorial I’ll refer to the popular graphical client TortoiseSVN.

Create a repository

Every project has its own repository, that is the space where the project files will be stored, this is represented by a folder that will contain your committed files³ and auxiliary SVN system files.

Normally it lies on a remote machine⁴ this should be a server. To setup a server check the official documentation.}, but to make the example fast to be run, we’re going to create it locally.

• Choose a directory where execute all the next exercises⁵ and create another folder (here named svn repo) that will be used to contain the repository itself.
• Select the svn repo folder and create the SVN repository: TortoiseSVN -> Create repository here (figure 4).
• A pop-up window will appear (figure 5) to choose which directory structure must be used for the service. Most of the times the default structure will be fine, then press: Create folder structure.
  Repository is now created with all SVN files needed to manage the versioning service. A message will confirm the directories creation, and the folder icon will be replaced by a new one (see figure 11a).

Figure 4: Create repository with TortoiseSVN.

Figure 5: Repository has been created.

SVN working directory structure

If we did not have a version control system, every time we would like test/develop something we should create a temporary folder with the desired branch.
If we had also the necessity to save all the eventually released version we should then create even another folder for every software done. Obviously this procedure, as well as being error prone, will soon led you to a mess in your project.

When Subversion initialize the repository it starts by default with three folders: trunk, branches and tags that represent respectively what we call the working directory, the develop directory and the release directory.

These three directories (branches on repository) could be linked to the respective local folders that can have different names, or might point to the same working folder⁶ and from time to time switch to one of the other (figure 6). This is by far the most used way.

You can think at the local folder as it would be a “folder shortcut” of the respective safely stored in the repository.

Figure 6: Subversion default folders structure.

Developing code using only the main branch (trunk) is not the right way to use the VCS. To make full use of a versioning it is advisable keep on the trunk only the software version with complete functions. A branch under the branches path should be created when starting to implement a new feature or test some functionality. When a functionality is complete and well integrated it can be then merged back in the main software (trunk branch).

Finally the tags branch should be used every time that a software is released. This workflow is well depicted in figure 7.

Figure 7: workflow used with a version control system.

To find out more on this you can read a really nice post (A successful Git branching model) on this blog.

Checkout a repository

All files/folders of a project are normally contained in a root folder (the working directory), to keep it under version control system, it is necessary “connect” this local folder to the repository. As seen this is normally linked to the trunk branch in the SVN repository.

• Inside the Exercises directory create the working folder (here named working).
• Select that directory and with right click choose: SVN Checkout… (figure 8).

Figure 8: Checkout repository to local folder.

• A pop-up window will appear (figure 9) to let you select both the repository url and the checkout folder. In the URL of the repository field insert the path to the repository directory svn repo and then select the trunk. You can use the repo-browser (using the button beside the textbox) to navigate the repository tree.
• In the Checkout directory field insert the working path (should already be correct).
• Then confirm the checkout.

Figure 9: Checkout trunk directory.

If everything has been done correctly a successful message window will appear (figure 10) to confirm you that “the link” between server and client has been established.

Figure 10: Checkout sucessfully completed.

Now the working directory is under SVN version control and this is showed by the new icon (figure 11b).

Figure 11a: SVN repository icon.

Figure 11b: SVN system icons.

Working on a project

When you start a project, you normally create and/or copy some files to the working folder.

Every time you make changes into files, of course these are saved, but what about if you would have liked to see something that you had and then has been changed?

In the course of time your project grow with new files, how can you check when these were been added to the project?

As you can see in figure 12, version control systems allow the user to manage all these aspects; in the following section will be presented the necessary commands to interact with the repository.

Figure 12: Commit timeline of the project.

Adding files

As you start a project you have to create and/or copy a certain number of files. No matter what is the action made, it is always necessary to inform SVN which files it does need to consider.
It is not enough just insert files in the working directory, in fact sometimes the user doesn’t want keep track of all files, i.e. temporary files, auto-generated files etc.
This is the reason why versioning software lets the user decide which files are to be included in the compilation.

• In this example I’m going to create/copy 2 text⁷ files: f1.txt end f2.txt in the working directory. They will appear with a new icon that means that they are not under version control system (figure 13a).
• To include them in the version control, select all files and with right click choose:
  TortoiseSVN -> Add (figure 14). Now these files will be added to SVN and this is showed by the new file icon (figure 13b).

Figure 13a: Files not under SVN.

Figure 13b: Files added to a VCS.

Figure 14: Add project files into the SVN repository.

To safely store the added files to the repository we need one more operation: the commit.

Commit files

Commit can be thought as a point where something important happens, so it must be possible to return whenever will be necessary.
This operation allows the user, through the client, to store these files on the repository, associating files with a unique number accompanied by a descriptive user message.
Figure 12 shows a typical project workflow: files are first added, then the changes are committed to the repository.

• To commit a project, select the added files or the working dir, then right click and choose SVN Commit… (figure 15).

Figure 15: Commit project files.

• In the window summary (figure 16) insert the commit comment related to the modified files. It is important use a self-explanatory comment⁸ in order to be able to remember the state of the project at the “X” commit.

Figure 16: Commit window with the user message.

If everything has been done correctly a successful message window will appear (like figure 10) to confirm the operation. Now files icon should look like in figure 17a.

Suppose now that to add some functionality to our first function we need to modify the two previous files and add a new one; the situation will appear as in the figure 17b.
We see that f1.txt and f2.txt have been modified, while f3.txt has been only added to the project directory. If we want that it would be part of the project we need to add it as previously done with f1.txt and f2.txt.

At the end of the operation, the folder contents will be represented as in figure 17c.

Figure 17a: Files up to date.

Figure 17b: Files edited and not versioned.

Figure 17c: Files edited and added.

Now as you may have guessed, to store and sync the modified files to the repository it is necessary execute the commit operation (figure 12).

Again, if everything has worked properly SVN will ask to the user to insert an explanatory commit message as seen before (figure 16).

Update files

When you work on a common project all files can be edited by anyone in your group, so before you start to work, you have to update your local copy to reflect the changes in the repository that maybe someone did.

If someone change and commit a certain file, your local copy is not more up-to-date with the project development. If you edited the same file without updating your local copy first, you could end up with a conflict (figure 18).

Figure 18: When the user doesn’t keep the working dir up-to-date he can get in trouble.

If users do changes to the same file, versioning systems can understand if the changes done are compatible, and in that case it is going to “merge” both.

When the changes aren’t compatible (for example both users edit the same function), the versioning systems can’t decide which are the right files part to keep, o to merge. In this case you’ll end up with a conflict that the user must resolve to be able to commit the project.

To update your working directory:

• Select the project folder, then choose SVN Update (figure 19a).
• If the process complete correctly, a new window will confirm you that both local and repository copies are up to date to a certain revision number.

Figure 19a: The update allows the user to sync his local revision with the last on the repository.

Figure 19b: Using Update to revision the user can move back and forth on the project commits.

From this point the user can continue to work with the safety of not encountering any conflict.

Update to release

To move back and forward on the project history (commits) the user needs to use the “update to revision” command.

To update your working directory to the desired version:

• Select project folder, then choose TortoiseSVN -> Update to revision… (figure 19b).
• A new pop-up window will appear (figure 20), press the Show log button to list all the available commits.

Figure 20: The user can select the desired commit using the Show log button, or insert the right number in the field below.

• Select the desired commit from the list (figure 21).
  The number of the selected revision will appear in the field below the button (figure 20). Finally execute the update. If the process complete correctly, a new window will confirm you that both local and repository copies are up to date to the selected revision.

Figure 21: This window allows the user to select the desired commit.

To return the project to the last revision just use the SVN Update command.

Another useful feature of the update command is that we can execute it without the fear that the changes did at the local files would be overwritten. For example you and a your colleague are working at the same project but on different files.
Sometimes you both want to have a peek of each other. Using the update command you will be able to “download” his new version of the file without losing changes that you did in yours.

Revert files

The last command of this section, is useful when you want to discard all changes made at the project files and revert to the last revision present in the local folder.

For example after committing your project you want to try to fix a bug, but as soon as you start to edit the code, you realise that there is one more important to be fixed first. So, to quickly restart the job, exactly from the last commit, you have to use the revert command.

Pay attention that any “update” command does not discard the changes! This is a desirable behaviour, since we want to avoid losing any development done in the project when wishing to update remaining project files.

If we update 2 files of our example project, but before commit you decide that only one is correct.

To discard your changes:

• Select the working folder, then with the right click select TortoiseSVN -> Revert… (figure 22a).

• A pop-up window will appear let you select the modified files to revert (figure 22b). The selected file will be resetted at the same point where it was at the committing time.

Figure 22a: With the revert you can discard all/some changes of the project

Figure 22b: You can decide which edited file revert.

Branching and merging

As suggested in the (SVN Workinkg directory structure), the branch can be useful to develop something that we are not ready to insert, or that we are not sure that we want into the main program. Similarly, the merge operation allows the code to be inserted in an existing branch.

Branch project

Related to our example, suppose that after some work on the project we are ready to add a new functionality (named niceFunction).
In this case we might start to develop this function on another branch in order to maintain the trunk always as “working” branch.

To create a branch for our project:

• Select project folder, then choose TortoiseSVN -> Branch/tag… option from the menu (figure 23a), a new pop-up window will appear (figure 23b).

• To create the branch under the branches directory, write into the To path: field the desired branch name (figure 23b).
  Finally choose the radio button HEAD revision in the repository and select the checkbox Switch working copy to new branch/tag and complete the operation with a log message.

Figure 23a: Create project branch

Figure 23b: Add branch folder.

Now the local folder will be “connected” to this new branch: niceFunction, and it is possible start to create the desired function on the branch (figure 6).

Merge a branch

When we want to merge into the main program (the trunk) a functionality that comes from another branch or repository, we need to execute the merge command.

Referring to our example, let’s say that we successfully completed the function created in the branch niceFunction and then we want to merge it into the main trunk of our project.

Be aware that, to successfully execute the merge command it is necessary be on the folder that will receive the update. So if we are still in the branch niceFunction it is necessary to switch from the local copy to the trunk.

To merge the example:

• Select the working folder and choose TortoiseSVN -> Switch… (figure 24a).
  A new pop-up window will allow you to select where the local folder should be switched to; in this case select the trunk (figure 24b).

Figure 24a: Switch to branch.

Figure 24b: Select the trunk branch.

• Select the project folder, then choose TortoiseSVN -> Merge… option (figure 25a).

• In the appeared window select the option Merge two different tree (figure 25b) and continue.

Figure 25a: Merge branch menu.

Figure 25b: Select the desired merge type

• A new window will appear (figure 26a) querying to insert the path for the From: and for the To: fields. This will “sounds” a bit odd, but the first⁹ field needs to be filled with the url of the trunk.
  Fill the second field with the url of the branch that we want to transfer into the trunk (in this example the niceFunction).
• We are finally ready to merge both branches. Before executing the command it is preferable to test it using the dedicated button (figure 26b).

Figure 26a: Select the branch to be merged into the trunk.

Figure 26b: Execute the merge into the trunk branch.

• At this point two scenarios are possible:
  • there aren’t conflicts and the merge complete straightforward;
  • there are conflicts and the user must resolve it to complete the merge.

Figure 24a: Switch to branch menu.

Figure 24b: Select the trunk branch.

In the first case, we can simply execute the command finding the new function niceFunction inserted in the main program, while in the second case we need to resolve the conflict to complete the operation.

Resolve conflicts

A conflict occurs whenever two or more users edit the same document “at the same time”, and not seeing one of the changes that the other is making it may overlap. Since the software is not smart enough to decide which of the changes is “correct”, it requires the user to resolve the conflict.

Let’s say that in the file f2.txt the code has been defined a string:

uint8_t string[] = "Text";

At the some point of the development someone edited and committed that line of code to:

uint8_t string[] = "Wrong text";

In the mean time (since you didn’t update the project, so you are still on the previous revision) you change the very same line of code to:

const uint8_t string[] = "Right text";

As soon as you want to commit you’ll receive a message that warn you about a conflict, and that it must be resolved before you’ll be able to commit the job.
In this case your working folder icon will look like figure 27a, while your files like figure 27b.

Figure 27a: Working directory icon during a conflict.

Figure 27b: Files contents of the working directory during a conflict.

You will see that now that the working folder has different files that you hadn’t. In particular for this example they will become:¹⁰

• • with the yellow warning icon;
  • <file name>.mine;
  • <file name>.r<revision number of your local working folder>;
  • <file name>.r.<revision number on the remote repository>.

The third file in the directory (named f2.txt.mine) contains what you just tried to commit.
The fourth one (named f2.txt.r51) contains the revision you started to work on.
The second last file (named f2.txt.r52) contains the last commit that you missed, and that is causing the conflict with your code line.

Finally the file contains the same line of code taken from each previous file, and expressed as:

<<<<<<< .mine
const uint8_t string[] = "Right text";||||||| .r51
uint8_t string[] = "Text";=======
uint8_t string[] = "wrong text";>>>>>>> .r52

The text contained between the symbols “” is the one updated by someone else and related to the revision specified at the end; in this case 52.

To solve this conflict it is necessary to edit¹¹ the file removing all the unwanted text; so in this case the previous block must be changed to:

const uint8_t string[] = "Right text";

To complete the conflict resolution it is necessary notify SVN that the conflict has been solved, using the resolve option (figure 28a). A new window (figure 28b) will appear letting the user select which is the file to be marked as solved¹².

Figure 28a: At the end of the conflict it is necessary communicate to SVN that the conflict has been solved.

Figure 28b: A new window will let the user select the file to be declared solved .

Another type of conflict that might arise, is when branches are merged.
Image that someone updated the main trunk while you are working on the branch. If quite the same part of code is changed, as we saw, this might led to a conflict.

In this case, when we know that the right code lie in the local repository, or in another branch we can directly choose the relative button (Prefer local or Prefer repository) to accept the desired file version (figure 29).

Figure 29: TortoiseSVN asks to the user to resolve the conflict.

When we don’t know what are the changes present in the other trunk we need to choose Edit conflict and manually select the right lines of code as explained in the previous part.

In figure 30, similarly to the files in the previous example (figure 27b), are showed the contents of the files in the repository (left side), the contents in the working folder (right side) and finally the merged result, that in this case needs to be updated by the user.

Figure 30: TortoiseSVN show the conflict that prevent to merge the branch into the trunk.

If for example we want to keep the text nice function instead of the naughty function, we can use the right click menu on the highlighted text and select the desired source. Even more it is possible keep the entry file from one source or from the other (figure 31).

Figure 31: TortoiseSVN allows to select the desired line of code from both file versions.

Obviously it is also possible select mixed line of code from both file versions, the bottom window contains what in the end will be committed.
When the merge is completed, save the changes and close the editor.
Lastly, to complete the merge, select the the button Resolved in the conflict window (figure 29) that now should be enabled.

Tag a software release

Every time you create a stable software that you want to release, you might take note of which commit is, or rather, tag that commit. This will create in the Tags folder only well defined working software versions.

To tag a software version we have to proceed quite as we did to make a branch:

• Update the working folder at the desired release version.
• Select the folder, then choose TortoiseSVN -> Branch/tag… option from the menu (figure 23a), a new pop-up window will appear (figure 32a).
• To create a tagged software, point the field To path: /tags/¹³> and in this case, select the radio button: Specific revision in repository. This is necessary to “link” the desired revision with the passed tag name.

Figure 32a: Tag a certain software version to be released.

Figure 32b: Folders containing released software version.

Now you end up with a similar situation reported in figure 32b, where every release has its own folder; in this way you will have always at hand the desired software version. You can also add an eventual release note file that contains all details of that version.

Advanced functions

In this section I will present just some useful functions to use in Subversion. These are not complicated concepts, but something over and above the typical normal software use.

Include externals

In some cases it might be really useful pack more repository together, to reuse something that you developed in the past, or to organize a work that has heterogeneous repositories.

For example, let’s say that we want to add a new functionality to our project using a library (that has its own repository) previously developed.
To quickly solve the problem we could just copy these files into the project folder, or to solve it brilliantly, we might use the externals project properties.
This function links the library and the project repositories together to end up with a commit that includes every necessary files to build the project (figure 33).

Figure 33: SVN with its externals property allows to link different commits from various repositories.

To test this functionality we need to create another repository (named svn repo lib) and its working folder (named library) (figure 34a).

Here the steps to apply the externals project properties on our example:

• Open the SVN properties on the project folder (working): TortoiseSVN -> Properties (figure 35).

Figure 35: Open project properties.

• In the new window select: New -> Externals (figure 36), a pop-up window will appear to let you insert the external repository (figure 37).

Figure 36: Select the repository properties.

• In this new window press the button New again and a pop-up will allow you to insert the path to the external repository and its details for the desired commit (figure 37).

Figure 37 – Add a new external and specify all the details related to the “linked” repository.

In that window you will see the following fields:
Local path: is the name of the directory that will be created inside the project folder to contain the external committed files. For the example, this is named: Driver (figure 37).
URL: is the path to the external repository. Use Repo-browser to correctly find the desired folder. In this case I’m pointing to the trunk of the external library repository.
Revision: can be any commit. Use the radio button to choose the last (HEAD revision) or any other (Revision). In this case I pointed to a certain library version.

• Finally to conclude the operation it is necessary to execute the update command (to checkout the externals files in the project directory), and the commit command to finalise the application of the external properties to the project folder (figure 34b)

Figure 34a: Folders of a project linked to an externals properties.

Figure 34b: Commit files of a project using an externals repository.

Pay attention:
If you select the HEAD revision option (figure 37) the externals included will always point to the last commit of that repository.
To use a fixed version select the Revision option and pick-up the desired commit through the Show log button. This is by far the suggested option to use.

Using the HEAD revision option you have to take in account even another point:

• If the externals (Driver folder) has a repository (svn repo lib) located in the same project repository (svn repo folder), any commit done to the library (library folder) will be reflected also in the linked folder present in the project (driver folder) at the commit time.
• If the externals (Driver folder) has a repository (svn repo lib) located on a different path (as we did in this example), any commit done to the library will be notified at the time to commit the project (working folder), then to keep the externals up-to-date the user must update first the project folder before committing the entry project¹⁴.

The externals can be identified even from the repo-browser. They appear with an icon (a blue arrow) which remember the Windows OS shortcut system icon (figure 38).

Figure 38: The externals files/folders are showed in the repo-browser with a different icon.

Lock a file

In some cases, before starting to work on a file, it is convenient to keep lock on it while editing.
When the project is shared between people, there is a chance that more than one person is trying to edit the same file, as seen, this might give rise to conflicts.

If this is text file there should be fewer issues with multiple editors (as seen in section Resolve conflicts), but if this is a binary file (such a CAD format), then merging multiple updates is likely to corrupt the file.

To avoid this situation only one person at time should update that types of file.
In this case it is suggested to use the SVN lock file function.

Before starting to work on a file you should lock it so that other users cannot commit their changes until you have committed yours or voluntarily relinquished the lock.

To lock a file:

• Select the file to be locked then choose: TortoiseSVN -> Get lock… (figure 39).

Figure 39: Before start to work use the TortoiseSVN menu to lock the file.

• A new window will appear asking the user to insert an optional message that will be showed to users that try to commit changes on the same file (figure 40a).
• At the end of your work, as soon as you’ll commit the job, the lock will be automatically released. If, for some reason you want keep the file still locked you have to check the box Keep locks visible in figure 40b.

Figure 40a: Let other users know who is locking the file inserting a meaningful message.

Figure 40b: At the commit time the user can decide if release the file or continue to keep it lock it.

This mechanism for sure can prevent to corrupt files, but it can’t save the users from wasting their time.

In fact suppose that for a misunderstanding, you and a your colleague start to work at the same time on the same binary file; he locks the file, but you forget to do it. After hours of hard work, you are proud to commit your job, but soon you realise what’s happened. >:(>:(>:(

Is it possible to prevent this scenario? Yes it is.

Subversion has a property that force all working files to be read only (in their default state), except when a lock is applied to a file. In this situation the user will be forced to lock the file before to start to work on it, thus making the file editing mutually exclusive.

To apply this property it is necessary to proceed as we did to apply the externals, but of course selecting this other property.

• Select the working folder and then TortoiseSVN -> Properties (figure 35).
• In the new window choose New, and select Needs-Lock from the drop-down menu (figure 41a).
• A new dialog box (figure 41b) will let the user select which kind of lock is required. To make the project file read only as default, choose the option Locking required(read-only update) and confirm.

Figure 41a: Add the Needs-Lock property to the project.

Figure 41b: To make the file editing mutually exclusive select the first option.

Now all files in the working directory are read only. This should be displayed by the gray icon instead of the green one. Unfortunately due to a limitation of the Microsoft OS this, doesn’t work¹⁵. To fix the problem a workaround exist, but it is more fast (and safe) just open the file and check if this is read/write.
Quite a number of text editor have an icon relating to the read/write state of the file, for example Notepad++ has an icon on the file tab whose color depends on the file state: gray for read only and blue for a read/write file.
To run this example is necessary to use another “user” from the same machine or a different machine, and of course, create a repository accessible from both users. Create then a local working folder that point to this common repository.

• Lock the file you want to start to work on.
• Change user and try to lock the same file. In this case, before starting to consume your time you’ll been advised that the file has already been locked by the other user (figure 42).

Figure 42: When another user locked the file you can’t even start to working on it, this will save you some time.

To find out more refer to the official documentation.

Using SVN from command line

When you need to automate a process, TortoiseSVN shell is not more suitable,
in this case you need to use the SVN command line.

To verify your SVN command line installation: Open the command window in the working directory and launch the command: svn info.

C:\Users\AleTheCoder\Desktop\Exercises\working>svn info
Path: .
Working Copy Root Path: C:\Users\AleTheCoder\Desktop\Exercises\working
URL: file:///C:/Users/AleTheCoder/Desktop/Exercises/svn%20repo/trunk
Relative URL: ^/trunk
Repository Root: file:///C:/Users/AleTheCoder/Desktop/Exercises/svn%20repo
Repository UUID: 187e5647-e797-8842-a3b1-6eedd41a4370
Revision: 66
Node Kind: directory
Schedule: normal
Last Changed Author: Ale theCoder
Last Changed Rev: 66
Last Changed Date: 2018-01-21 15:25:22 +0000 (Sun, 21 Jan 2018)

If you get a similar output of the list above, then you are ready, but if you get an error, you miss the installation of that feature. To install it refer to section Install the software.
If you still have the same problem you might have to add the SVN command to the path¹⁶ environment variables.

Commands

Below (next list) I reported some of the most used SVN commands to successfully manage a project creating your custom functions.

• add files or directories to the working folder;
• commit the working folder;
• revert the selected file, or the whole working folder;
• update the selected file, or the whole working folder;
• checkout the repository at the last or at the passed revision;
• extract the desired file from repository in the present folder

To get the complete list of the available SVN functions see the official documentation.

# svn add command - force also already added files
svn add --force

# svn commit command
svn commit -m "commit message"

# svn revert command - discard changes of the files under VCS
svn revert -R

# svn update command - do not discard unsaved changes
svn update

# svn checkout command - checkout last revision
svn checkout

# svn checkout command - checkout passed revision
svn checkout /@

# svn export command - save in the current dir the last version of a specified file
svn export --force
#
# of course replace the contents of the angle brackets with the one you use
# for example to add write: svn add --force C:/home/AleTheCoder/Project/

In some cases, like before a commit, you might want to make appear a dialog box.

You can do easily invoking the TortoiseSVN shell¹⁷.

Below is reported the command to launch the TortoiseSVN commit command for the working folder used in the previous examples.

# prompt TortoiseSVN commit window for the Example
TortoiseProc /command:commit /closeonend:1 /path:C:\Users\Ale\Desktop\Exercises\working /logmsg "This is a commit launched from the command window!"

You will see appear the same window that you see when you call the commit from the shell (figure 16).
Of course it has not really sense launch these command from the system cmd when you have the shell. These are in fact useful when you have a program that need to interact with SVN (like a Python script).
To show you how to use these commands I created a Python function to invoke the commit command in both versions: using TortoiseSVN and using the SVN command line:

# Python function to commit the working folder
def svnCommit(filePath, commitMessage, visible)

# import module to execute windows commands
import subprocess

# is the visible flag true?
if visible:

# yes -> execute the commit command invoking the TortoiseSVN client
cmdCommit = 'TortoiseProc /command:commit /closeonend:1 /path:' + filePath + ' /logmsg ' + '"' + commitMessage + '"'

else:

# no -> execute the commit command invoking the SVN command like
cmdCommit = 'svn commit -m "' + commitMessage + '" ' + filePath

# execute the command through the window shell
cmd = subprocess.call(cmdCommit)

# Test code - run the svnCommit function
path = "C:\Users\AleTheCoder\Desktop\Exercises\working"

# run the commit through TortoiseSVN
svnCommit(path, "This is a commit message", True)
#
# uncomment to run the commit through SVN
#svnCommit(path, "This is a commit message", False)

Fast help and suggestions

Common mistakes

Either you’re new or not to a version control system you may incur in some common mistakes, here a quick troubleshooting list:

• working files don’t update;
• I can’t delete project files;
• I can’t rename a file correctly;
• write a commit log.

Working files don’t update

I’m trying to update the local folder to the last or selected commit, but files still remain at the same point.

Every time you modify a versioned file, imagine what happens if instead of committing all your hard work, you press the updated button by mistake and the system resets all changes? ;( ;( ;(

This is the reason why, when you press the update button the selected files or the entire folder doesn’t discard the last updates. In this case to discard the last modification you should execute the shell Revert command (section Revert files).

If you are still in trouble and there is a “mess” in the folder you can also delete all¹⁸ the contents and then run SVN Update (figure 11b). This will remove all the files (edited and not) that might create a conflict. The update command will “download” in your working directory all the files related to the last commit.

I Can’t delete project files

I tried to delete some working files, but after an update they are still present.

If you have a project that might evolve in a different way (sometime files are added, sometime files are removed) you have to delete these project files in the same way as you added them, that is using the TortoiseSVN shell.

Select the file that you want to remove and choose: TortoiseSVN -> Delete (figure 43).

Figure 43: To delete the project files you have to use the TortoiseSVN shell.

Now that file will be no longer “linked” to the VCS. If you only would delete the files from the working directory without using the SVN command, these files would still be part of the project. That explain why every time you use the update command, the version control system download also them.

I can’t rename a file correctly

I tried to rename a file, but it doesn’t look under version control, and when I update the old file still exist…

This is correct, since you renamed the file using the system command and not SVN. I’ll try to show you why.
For example, you want to rename the file f2.txt that is actually under version control, since has been added at the project creation. Now, using the Windows shell, you rename it to fileFunction.c. At this point SVN doesn’t see anymore that file, it is like it was deleted, so in case of the update command, this will be copied again to the working folder. Even more the renamed file is not under version control. As you might have guessed to rename the file you have to use the TortoiseSVN shell. This operation can be thought as a series of these commands: remove the file f2.txt from the version control system, rename the file to fileFunction.c and finally adding it to Subversion.

Write a commint log

How should I write a commit log?

Probably this is a question that, like me, many of you had had. I tried a lot of different methods and I searched online for useful advice, and in time I think that I arrived up to 90% of the job. A friend of mine (Matt) gave me the remain 10%! ;).
I’ll try to explain what work for me, but of course, there isn’t a right rule, so you can personalise it how do prefer.
The only important thing is that the message will be clear and self explanatory about what you made in that commit.

So what I use? I divide the message in two parts:

1. the version number;
2. the changes done in that commit.

The version number follow this schema¹⁹: MajorNumber.MinorNumber.PatchNumber where:

• Major number this number must be incremented when an incompatible change is done;
• Minor number this number must be incremented when you insert a functionality that is backwards compatible;
• Patch number this number must be incremented when a bugfix or a compatible function is added.

After this version number I insert a general overview of what I did, then in the follow lines I describe point per point what I changed and what I added or removed. The text is always lower case (except few exception) using these keywords:

• added when a file/function has been added;
• updated when a file function has been changed;
• removed when a file/function has been removed;
• fixed when a bug is resolved.

Here some examples:

0.0.1 – project started
– created the repository
– added the files “f1.txt”, “f2.txt” at the working folder

0.1.22 – started to create the function “readTemperature” – work in progress
– added the I2C driver to read temperature from sensors
– updated the function “readTemperature”, now convert to degC

0.2.0 – completed the chapter 3
– fixed the chapter typos
– updated the list of components
– removed the section about the pipe

Useful suggestions

Here I grouped some tips that might be useful to use and to understand Subversion better.

• I want to see the project history and its commit messages;
• I want to change the commit message;
• I noted that every file has its own version, why?;
• I would like to share a SVN project with friends;
• add a program to system PATH environment variables;
• is there a “cheatsheet” related to the VCS workflow?

I want to see the project history and its commit messages

To view all the project history you can use the Show log option from the TortoiseSVN menu on the working dir. Through this menu (figure 21) you can see all the commits, the revision number, its message and the files committed.

I want to change the commit message

I made a mistake writing a commit message.

SVN has the ability to let the user update the commit message. This function can be useful in case of typo or to add forgot details to a commit.

• Select the commit you want to edit from the Log Messages window and with the right click choose the option Edit log message from the drop-down menu (figure 44a).
• A pop-up window will appear, that lets you change the commit message. Edit the message and confirm.

Very likely you’ll receive an error message (figure 44b), this is due to a protection in the SVN configuration files, classic of a default system configuration.

Figure 44a: From the drop-down menu select the Edit log message option.

Figure 44b: On a default installation you can’t edit the commit message.

To enable this feature:

• Find the file pre-revprop-change.tmpl located at the path: /hooks²⁰
• Rename the file extension from *.tmpl to *.bat.
• As in the example below, comment the code related to the changing properties, and add the last two line.

# CODE PRESENT IN THE FILE: pre-revprop-change.bat THAT MUST BE COMMENTED OUT

#if [ "$ACTION" = "M" -a "$PROPNAME" = "svn:log" ]; then exit 0; fi
#echo "Changing revision properties other than svn:log is prohibited" >&2
#exit 1

# CODE TO ADD AT THE END OF THE FILE: pre-revprop-change.bat
@echo off
exit /B 0

If the file has been changed properly, re-executing the previous steps will now change the commit message.

I noted that every file has its own version, why?

In figure 12 is reported how a version control works without deeply discuss the way that SVN uses to version the project files.
The following diagram (figure 45) explain how Subversion “tags” a file with a certain number. We see that this match the commit number (of the project) where it took part. That explains why some file look up-to-date, and others not. You can easily check these numbers comparing the Log Messages window and the Repository Browser (figure 46)

Figure 45: This is the way how Subversion tags files version.

Figure 46: Here is showed how Subversion tags files version.

I would like to share a SVN project with friends

I would like to use Subversion at home for my stuff, but of course I don’t have a server. How can I do?

When you want to use SVN at home you could create the a local repository as seen for the example, but of course this is not safe, so this is not the best option.

In this case you might want to use a cloud service like: RiouxSVN (figure 47) with this you can create and use your own repository. Of course it also possible let other members collaborate to your project.

Figure 47: Some clould services allow you to use SVN for your personal projects.

If you want, you can even use a domestic NAS²¹ or create a new one using a microcomputer like Banana Pi… The NET it’s plenty of tutorial on these kind of arguments.

Add a program to system PATH environment variables

When you install a fresh copy of the operating system your command window knows only commands belonging to the standard Windows OS.
If a new program is installed and you want make it run from the command window, you have to register it into the system.

Open the Windows Control panel and choose System, then select Advanced system setting and a new window will appear (figure 48a).

Figure 48a: Open environment variables.

Figure 48b: Add TortoiseSVN to the system path.

In the tab Advanced choose the Environment Variables… button, a new window will appear again (figure 48b).
Under the panel System variables find the variable Path and edit the string, appending at the end of the existing line, the path to the executable program to add.
Remember the semicolon before add your path! The line should looks like follow code:

C:\ProgramData\Oracle\Java\javapath;%SystemRoot%\system32;%SystemRoot%;C:\Program Files\TortoiseSVN\bin.

Confirm the changes and restart the command window (cmd), you should now be able to launch the program added.

Is there a “cheatsheet” related to the VCS workflow?

Yes there is! Below you will find an useful (I hope) graph showing how use a version control system on your projects. Here the PDF file.

Footnotes

1) See the vertical dashed line in figure 1.↩
2) In a version control system all operations must be atomic.↩
3) Not in an intelligible form.↩
4 As wrote in the Introduction this should be a server. To setup a server check the official documentation.↩
5) My root exercise folder is named Exercises.↩
6) This depends on the development model that you want to use.↩
7) Of course they can be any files type.↩
8) See the subsection Write a commit log.↩
9) Yes this is not a typo, to find out more press the TortoiseSVN “Help” button.↩
10) The “angle bracket” will exactly replace what is contained in. For example in case of the file name, it will be f2.txt.↩
11) Yes! Manually!!!↩
12) This is of course necessary in case of conflict on different files.↩
13) For example 1.0.0.↩
14) This is what I found in the official documentation, however when I tested it, its behaviour has been as it had would been in the same project repository. Actually this is a bug, I checked the changelog file.↩
15) To see all the available icons go to the TortoiseSVN -> Settings and select the Icon Set submenu.↩
16) See section Add a program to system PATH environment variables.↩
17) To find out more visit the official page.↩
18) Pay attention, you are going to loose all your changes.↩
19) Thanks to Matthew C.!!!↩
20) In my case is: C:/Users/Ale/Desktop/Exercises/svn repo/hooks.↩
21) Network Archive Storage.↩

Ale theCoder
V 1.0

Other resources

Here you can download the LaTeX PDF version of the article.↩

Here you can find the source code of the document.

Advertisement

Privacy Settings