SVN Glossary

The SVN terminology can be confusing at times, this is a (probably incomplete) list of terms explained:

Add

Just moving new files into your local folder doesn't do anything, you also have to add them (in Tortoise, use right-click SVN -> Add). Adding files will only mark the files as candidates for the next commit, the actual upload to the SVN Server takes place the next time you commit your changes.

Once you added your files, TortoiseSVN will mark your files with a small blue plus sign, which indicates that they will be uploaded to the repository the next time you hit SVN>Commit.

Note that you can revert the files marked for addition before you commit them. This lets you un-mark them in case you selected the wrong files by accident.

Files added to the repository will become versioned, meaning that they are "under version control" from now on.

Blame

This applies to text-based files only. The blame option let's you see which line in a text file has been changed by whom and when. Especially useful for sourcecode files, when you want to find out when a specific line has been altered the last time.

Branch

A repository can contain several branches. There is always one main branch, called the trunk. The names are already indicating that the branch structure is a bit like a tree, or like arms of a large river. The trunk can be considered as the mainstream. It is always possible to create a new branch based on a specific revision (one speaks of branching off).

The branches are usually stored in a different URL, e.g.

• Mainline trunk: http://mysvnserver.org/svn/trunk/
• Branch called "mybranch": http://mysvnserver.org/svn/branches/mybranch

Branches are mainly used for code projects (like darkmod_src), it is of minor importance regarding the darkmod main repository.

Your local working copy is always referring to a specific branch (usually the trunk). You can switch your working copy to another branch, which will also update the local copy to the state the branch is currently in. When you perform a commit, the changes get committed to the current branch only.

With multiple people working on a repository, it is possible that the various branches get out of sync. Changes committed to the mainline trunk won't affect the other branches and vice versa. In order to keep the branches compatible with each other, the best practice is to copy/merge the changes from the trunk into your working branch in regular intervals. This way you make sure that your branch is always foot-on-foot with the trunk and the branch can be easily merged back into the trunk.

Once you're done working on your branch and you decided that the changes should become part of the trunk, one speaks of merging the branch into the trunk. There is a separate command in TortoiseSVN just for this purpose, where you can conveniently choose which revision range should be merged to where.

Checkout

Downloading a copy of a SVN Repository to a location on your hard disk is called a checkout. A checkout is the initial download of a working copy, not to be confused with an Update. You checkout a working copy once, but you can update it multiple times.

Commit

Just changing your local files isn't enough to "store" them in the server, you have to commit them. You need write access to the repository to be able to commit stuff. It is perfectly thinkable that the files you're about to commit have already been altered by another user. In the case of text/ascii files, the SVN Server tries to merge your changes into the files. If it fails (or if the files are not in text format (binary), the merge will fail and you run into a conflict.

Note: Committing files does not update your local copy, you'll have to do that manually. Note: Committing only affects the current branch your working copy is referring to.

Conflict

Let's say you have a working copy containing a few local changes (e.g. you made a change to a shader A in a material .mtr file). It's perfectly thinkable that somebody else has made a change to that .mtr file and committed that to the SVN Server. This means that both the .mtr file on the SVN Server and your local file have been altered. This has a few consequences:

SVN won't let you commit the .mtr (claiming your "local copy is out of date") - you'll have to choose SVN > Update first. By choosing update, the SVN software downloads the remote copy from the server, compares it to your local file (which has been changed) and tries to Merge the remote changes into your local file.

Two cases are possible now:

1. SVN can merge your changes: Let's assume the other user has updated a different shader B in a different location of that file. SVN will recognise that case and will apply the changes to your local file. After the merge your local file still contains the changes to shader A, which are ready to commit now. So practically, this was not a conflict, SVN could circumvent it. Note that text/ascii-files can be merged only (Binary files like textures can't be merged).
2. SVN cannot merge your changes: Let's assume a different user has made changes to the same shader A you were working on. SVN will see that the same section of the material file has been altered and will raise a conflict report during update. For text-based files, you can fire up the conflict editor (built-in in TortoiseSVN) and edit the changes manually, trying to resolve the conflict. However, usually this is not possible and you'll have to resolve the conflict in another way, normally by copying your changed file to a safe location and resolving the conflict "by using theirs" (right-click in the update window). See also the SVN Howto for a few possible Resolve approaches.

Delete

Just deleting the files from your local working copy won't let the SVN Server raise an eyebrow. The next time you hit Update, the deleted file will magically be restored by the SVN software. If you really want to delete a file from the repository, you'll have to specifically tell SVN to do so, by hitting SVN>Delete. This will mark the file for deletion (you can still revert that step). The next time you hit commit the file will actually be deleted from the HEAD revision in the repository and the change will also be visible to other users the next time they update their working copy.

Note: Even if you delete a file from the repository, it isn't lost forever. SVN keeps the revision history of each and every file in the repository and therefore you can easily retrieve the deleted version from the SVN history (e.g. by updating to a revision where the file still existed or using the repository browser). This is also the reason why the DarkMod's SVN server eats quite some disk space.

HEAD

The HEAD revision is a synonym for the most recent revision (= the revision carrying the highest number).

History

The SVN History includes all previous revisions of a certain repository. You can go back in time by choosing a certain revision number, which will "update" your working copy to the exact state the repository was in when this revision has been created. You can also browse through the repository using TortoiseSVN's Repository Browser.

Note that the complete file history is stored on the SVN server only, not on your local hard drive. Your working copy will only contain the files of the current revision (to be exact, it will keep each file twice to allow for easy revert operations without contacting the server).

Log

See also History. The SVN Log contains a list of all the revisions along with the date, the author responsible for the commit and the log message. The Log Message should briefly describe which changes have been made by that commit (and perhaps why).

Repository

The SVN repository is the "master container" containing all the files of a project, including all their history and other branches. An SVN Server can contain multiple repositories (e.g. our DarkMod SVN server holds the repositories darkmod, darkmod_src, texture_src, etc.). For downloading a repository, see Checkout.

Repository Browser

TortoiseSVN comes with a handy feature called repository browser. It lets you look at the files and folders in the repository at a given revision, like some Windows Explorer with a built-in time machine. You can also add and delete files via the repo-browser, but this is not the recommended way of changing the repository - only use this in occasions where you don't want to checkout the entire repository or if a specific file in the repository is broken and prevents you from checking it out.

Revert

Any local changes can be reverted. The command is accessible via the context menu in TortoiseSVN (SVN>Revert) In case you changed a file, the revert command will undo your changes and revert your file to the last checked-out/updated state (called the "working base").

Important: Reverting your changes cannot be undone! Your changes to the file will be lost! Keep a backup of your local changes if you think you'll need them for future commits. This is especially important when you run into conflicts. Reverting is usually not the right way to resolve conflicts.

Revision

Each time somebody performs a commit, the revision number of the repository is increased by one. It doesn't matter how many files you commit, or if the changes are minor, or if a file gets added or deleted - no matter what you commit, the revision number is always increased. The most recent revision is called the HEAD revision.

The advantage of having revisions is that you can go back to a specific point in the SVN history by specifying the revision number. For code changes this is especially useful: a bug in the software might be discovered now, but it may have been introduced long ago. By stepping back the revisions you can (more or less easily) find out when exactly the bug was introduced, which lines of code have been changed (see Diff) and by whom (see also Blame).

The revision system affects all files, also binary files like textures and Lightwave models, for instance.

For browsing the revisions, see also History, Repository Browser and Update.

Trunk

See Branch.

Update

Updating a local copy means synchronising it with the server. Choosing update will download all changes since the last time you updated your copy (files added by other users, text changes made to files, file deletions). The process will update your working copy to the HEAD revision by default, but you can manually choose to update to a certain revision if you wish.

During update, the SVN software will also try to merge changes into locally modified files (imagine both you and another user made changes to the same material file). If the changes can be automatically resolved, SVN will do so, otherwise a conflict occurs, which has to be manually resolved.