Version 4 (modified by janwas, 16 years ago) ( diff )

formatting; add note on commit comment on weblog

Using Subversion with TortoiseSVN

by Matt Holmes (Calefaction)

Definitions

Subversion; SVN: Link

  • "A version control system that is a compelling replacement for CVS in the open source community."
  • It records the history and manages changes to a repository of files by multiple users.
  • The programmers have been using a similar system called CVS for some time to manage our source code, and with SVN we've now rolled this out to include all game binaries/assets too.
  • It takes care of ensuring that we don't overwrite each other's files when we commit files to it, and checks what you've already downloaded against what's in the repository so that it'll only download things that have changed since your last update.

TortoiseSVN: Link

  • "A free/open-source client for the Subversion version control system."
  • An easy-to-use tool that integrates with Windows Explorer. It is used to access the Subversion repository.

Repository:

  • Files are stored in a central repository. The repository is much like an ordinary file server, except that it remembers every change ever made to your files and directories. This allows you to recover older versions of your files and examine the history of how and when your data changed.

Section 1: Creating Your Account

Request an account from Philip Taylor (Ykkrosh). Ensure you let him know your desired Password. You will also be given a User Name (typically your first name). This will be used as your personal login to access the SVN repositories.

Section 2: Getting and Installing TortoiseSVN

You can obtain TortoiseSVN from here. Select the latest version available for your operating system. Follow the standard installation procedure and reboot when asked.

Section 3: Making your first Checkout

Now we need to point you to the correct SVN URL and checkout the current SVN source tree onto your harddrive. The current SVN trunk url is:

For anyone except programmers:

http://svn.wildfiregames.com/svn/ps/trunk/binaries

http://svn.wildfiregames.com/svn/ps/trunk/docs

For programmers:

http://svn.wildfiregames.com/svn/ps/trunk

I also suggest creating a unique directory. I use the directory C:\0ad, but feel free to use whatever directory you see fit.

The directory you check the game out to should ideally have no spaces in its path. For example, C:\My Documents\0AD may cause problems.

Next, follow these steps to checkout the SVN tree.

1 In Windows Explorer, navigate to the directory where you want to check the SVN tree out to.

2 Right click to bring up the context menu. Select 'Checkout...' in the SVN section of the menu:

http://www.wildfiregames.com/~code/resources/guide/guide1.jpg

3 In the 'Url of repository' field enter the URL above. Leave all other fields at their defaults:

http://www.wildfiregames.com/~code/resources/guide/guide2.jpg

4 After pressing OK, a dialog refering to caching the SVN server's host key could come up. Accept that key if it does.

You should then be prompted for your account login. Enter the username and password you have requested. In some cases you may be asked for your password twice.

Once your password has been succesfully entered, you should see the repository beginning to download:

http://www.wildfiregames.com/~code/resources/guide/guide3.jpg

Note: This will take a while. That's perfectly normal. You're checking out over a hundred megabytes of stuff. Leave it to get on with it, and go do something else for a while.

Checkout puts a lot of strain on the server. If it times out, try checking out sub-sections of the repository at a time, or try again later when less members are downloading.

Section 4: Updating your files

A key component to any version control system is the ability to update your files to the latest versions available in the repository. Much like the rest of your everyday SVN operations, TortoiseSVN makes this extremely easy. The following steps will detail how this is done:

1 Select the file, files or directories that you want to update (NOTE: I suggest updating entire modules of the project at a time. For instance, update the entire 'source' or 'binaries' module, or both. This will keep your entire source base in sync with the Subversion tree. If you have a reason to only update a subset of the projects objects, then you may do that as well)

2 Right click to bring up the context menu. In the SVN section of the menu, select 'Update...':

http://www.wildfiregames.com/~code/resources/guide/guide10.jpg

3 You should immediately see a status dialog detailing what SVN is updating:

http://www.wildfiregames.com/~code/resources/guide/guide11.jpg

The next two sections describe how to add to or change the repository contents, and are only available to accounts with write access (artists and programmers).

Section 5: Making your first commit

Once you have made some changes and are ready to check them in, you will need to commit them. You can commit an entire directory (and all of its sub-directories), a group of files, or a single file. Use the following steps to commit files to Subversion:

1 Select the file, files or directories that you want to commit.

2 Right click to bring up the context menu. Select 'Commit...' in the SVN area of the menu:

http://www.wildfiregames.com/~code/resources/guide/guide4.jpg

3 Enter appropriate comments about the changes in the 'Enter Log Message' dialog:

The SVN comments are filtered so that they can appear on the 0 A.D. webpage and demonstrate our progress. Put a hash (#) in front of any line that you want to appear on the web log. All other lines won't show up on the website, but can still be seen in the TortoiseSVN log.

http://www.wildfiregames.com/~code/resources/guide/guide5.jpg

4 Press 'OK'. The commit should begin and you should see the following status dialog:

http://www.wildfiregames.com/~code/resources/guide/guide6.jpg

Section 6: Adding files to the repository

Before you can commit a new file to the repository, you must first add it. Adding files to the repository is much like committing them, just use the following steps:

1 Select the file, files or directories that you want to add.

2 Right click to bring up the context menu. Under the 'TortoiseSVN' sub-menu, select the 'Add...' option:

http://www.wildfiregames.com/~code/resources/guide/guide7.jpg

3 Confirm which files you want to add to the repository:

http://www.wildfiregames.com/~code/resources/guide/guide8.jpg

4 Press 'OK'. You will see a status dialog detailing what was added to the SVN repository:

http://www.wildfiregames.com/~code/resources/guide/guide9.jpg

NOTE: To finalise the addition of files to the SVN repository you must Commit the files you added! Follow the section on Committing files above to see how that is done.

Appendix

For programmers:

Note: See TracWiki for help on using the wiki.