How to commit changes to SVN

This tutorial assumes that you have a Working Copy of the darkmod repository checked out on your hard drive, in the folder C:\Games\Doom3. Furthermore, it's aimed at TortoiseSVN users.

Things to remember:

• Make your changes
• Update your working copy (RMB > SVN Update)
• Choose SVN Commit... in the context menu
• Review your changes in the commit dialog.
• Enter a log message (mandatory)
• Click OK to commit.

Initial Situation

The initial situation looks like this:

This is my current darkmod/ folder. As you notice, nearly all files are marked green (see also What are the red and green icons for?), apart from my maps/ folder. This means that one or more files in that folder have been changed by me and they are different to the versions on the SVN Server. A few files don't have icons at all, meaning that these files are not under version control.

Make your change

As first step, we are going to change a shader in one of the .mtr files. Let's go into the materials/ folder and open the target file in our favourite text editor. I'll take the player_equipment.mtr file and will add a comment to one of the shaders:

>>

As soon as you save your change in the text editor, you'll notice that the icon of the changed file will change from green to red. This means that TortoiseSVN has detected a difference in the file and that it will be considered for the next upload.

Update your working copy before commit

In case another user has been working on the same folder/file as you, it's advisable to update your working copy before committing your changes. This is not exactly mandatory, but it will help to avoid later troubleshooting. Any possible file conflicts will be pointed out in the Update dialog.

If you're fairly sure that no one else has updated the files/folder in the meantime, you can also skip that step.

Prepare for commit

Now that we've finished editing our file we can get ready for sending/uploading it into the repository. (This process is called "Commit" as you might have expected). Right-click the materials/ folder and choose SVN Commit...:

>>

In the following SVN commit dialog you will be asked to enter a log message describing your commit. Enter a brief message here to indicate what you've done with that commit (and perhaps why). In the list in the lower half of the dialog you see the list of files that will be affected by your commit operation. In our example, this is just the player_equipment.mtr file, which is ok. (If you changed another file in the same folder, it would be committed too, which might be undesired in some situations.) You can now uncheck any files if you want to exclude them from your operation. It's also possible to review the differences of text-based files, by right-clicking any file in the list and choose Compare with Base. This will open a new window with a convenient text viewer, highlighting your changes.

In our case, we're happy with our selection and we can proceed to commit, click OK:

You might need to enter your authentication details, in case you haven't committed anything yet or do not want to let TortoiseSVN to save your password. Once you entered your username/password, the commit progress dialog will be displayed, this should be finished fairly quickly, given our small change.

Background note: SVN is clever and only sends the actual difference of the files to the server. However, for binary files like textures this is doesn't work too well and SVN will usually upload the entire file. In any case, the data is compressed to save bandwidth.

Congratulations, you have committed your first file! By committing a change to the file you also increased the revision number of the repository ("Done, at revision 3982").

As soon as the commit operation is finished, the icon of that file goes back to green and an automatic mail is sent to all other Team Members to notify them about your change, including your username, your log message and the files you've changed.

Committing multiple folders

It's possible to upload the changes in several folders in a single commit operation. Proceed like this:

• Highlight the folders you intend to upload (they are usually marked red, as they contain changed files).
• Right-click one of the folders and click SVN Upload....
• The commit dialog will present all files in all highlighted folders. You can still fine-tune your selection in that list.

Troubleshooting

It's well possible that another user has changed the same file as you (player_equipment.mtr in this example). In that case, the SVN server can't just accept your commit, it will want you to update your working copy first. An error message like this will appear:

"Commit failed. Out of date. You have to update your working copy first."

In that case, you'll have to right-click the materials/ folder (or its parent folder darkmod/) and choose SVN Update. This will synchronise your materials/ folder with the contents on the SVN Server again and will try to merge the changes in your local file.

It is possible that the other user has changed the exact same section as you. In this case, SVN will raise a conflict warning and you'll need to edit/resolve the conflict. This is the topic of another article How to resolve SVN conflicts.