Civ 5 is already out, and its modding has already begun, but I still release this guide for two reasons: Civ 4 modding is still alive and kicking, and most of this guide is actually relevant for Civ 5 modding as well. (Jump to part II) Part I: The Basics Do not fear the change. Change is good. Especially if you can undo it easily. (an unknown poet) Introduction As I was browsing through the modding forums, I've noticed a recurring problem: modders that make changes, which somehow caused something to stop working. The more experienced modders make backups of they're work frequently, so they can always go back to a previous version and look for what went wrong, but this becomes tedious (and disk space consuming) very fast. The solution is something which is called "Version Control". Some of the modders (especially the software developers) use it all the time. All the big mods use it - BUG, BBAI and dozens of others which I don't know. Many of them (including BUG and BBAI) use Subversion as the version control system (through Source Forge). I'm not an experienced modder, but I would like to show those of you who don't use it a very easy way to add version control to your mod. This guide is mainly intended for those modders who make changes to C++ sources, Python or XML files, since this solution is better used for text files. You can use version control for art files as well (especially images), but for large binary files it might not be as effective disk-space wise. This is not the best Tortoise SVN tutorial out there, and by far not the most comprehensive one, but I tried creating a tutorial which is adapted to Civ4 modding. Most of this guide applies to Civ5 modding as well (lua files instead of python files etc.), but since I know nothing about it I will only refer to Civ4. Through out this guide I added spoilers with additional information which is not directly required to use it. Feel free to skip these and maybe return to them later. There is usually more than one way to do things with TortoiseSVN, and I show what I think is the fastest and easiest way. but don't be surprised if other people do it differently. Any comments, questions, ideas, corrections, tips, additions and money transfers are most welcome. What is version Control? Version control (AKA revision control, or source control) is a way to manage the history of your project. The version control software manages all the changes you make to your project files, and allows you to watch the history of these changes, as well as reverting to a previous version of your project and maintain several versions for it. When using version control, many people can work and make changes to the same project while the version control software synchronizes between them. This topic, however, will not be covered in this guide. What is Tortoise SVN? SVN stands for subversion. Subversion is an open source, very commonly used version control system. Subversion is both a software and a protocol, so different implementations of the subversion client can be used to access the same subversion repository. Tortoise SVN is a Windows shell extension, which is used as a comfortable UI wrapper for subversion client. This guide will demonstrate how to locally use Tortoise SVN with your mod. Some definitions first... Repository - The database which holds the entire project history. Can either be on a local disk or on a remote computer. In this guide we will create a local repository for your mod on your machine. Working copy - A local folder on your computer which points to a certain location in the repository. This is the folder where you actually hold your project files and work on the project. Commit - Applying a change (or a group of changes) from your working copy to the repository. Such changes can be modifying a file, adding/removing a file, creating a folder etc. Revision - A history item of the repository. Whenever you make changes to the repository (using commit, or directly through the repository browser), a new revision is created in the repository. Each revision might contain any number of changes. If you commit multiple changes at once, they will all be considered a single revision. Getting started Download the latest Tortoise SVN, and install. After installation, you can right-click in your explorer (not the web browser) on any file or folder, and You'll see you have a new "Tortoise SVN" section in the context menu. The menu might have different items depending on which file/folder you right-click. Before creating our own repository, let's look for an existing repository to familiarize ourselves with tortoise a bit. To watch an existing repository for which you don't have a working copy yet, select 'TortoiseSVN --> Repo-Browser'. Then you can enter a URL, for example "https://civ4bug.svn.sourceforge.net/svnroot/civ4bug", which will load the repository browser for the URL you selected. In this specific case, it's the BUG project. Since it's a remote repository to which you access using the internet, loading it might take a few seconds. It works a lot faster when you use a local repository. What you see is something like this: At the top you see the repository URL. To the left you can see the basic tree structure of the project. This is the standard: trunk, branches, tags. You can google it for more details. The most important folder is the trunk, which is the main development branch. To the right you see the contents of the currently selected folder: subfolders and files. Each of these items also displayes, in addition to other details, the latest revision in which it was changed and who made the change (author). Now, to watch the history of the trunk in this repository, right-click the trunk folder and select 'Show Log'. You will get something similar to this: You see a list of the revisions which were committed to the trunk and its subfolders. The log for a folder will include the changes made to its files and to its subfolders, so it's easy to view the history of whole sections of the project. When you click on a revision, you can see its log message in the middle panel, and the list of changes that are included in this revision in the bottom panel. Note that the log shows only the recent 100 relevant revisions. You can view more with the buttons at the bottom of the dialog box. Spoiler : You might notice that the numbers of these revisions are ordered from new to old, but are not always consecutive (see the leap between 2226 and 2221). This is because the revisions are numbered for the entire repository, and the log only shows the revisions which are relevant for the specific folder (in our case - the trunk). In the repo-browser view you can select the top repository folder and do 'Show Log' for this, in which case there will be no revision skips in the log. To see the actual changes made to a file, double-click one of the 'Modified' files in the bottom panel. A diff viewer tool will open comparing the two versions of the file: before and after the change. This diff viewer comes built in with Tortoise SVN, but you can configure it to use other diff viewers (most also can be used to move changes from one file to another). One of the most common (and my personal favorite) is WinMerge, which can also automatically register itself to be used with Tortoise SVN when installed. Spoiler : You can select multiple revisions using the Ctrl and Shift keys (same as in the file explorer). You will then see an aggregate of all changes made in this revisions in the bottom panel, and if you double-click a file, you will see all the changes made to this file in all the selected revisions. Now that we have a basic understanding of what a repository and a revision are, we can start actually using Tortoise SVN. Creating a local repository Create a new folder for your repository. Remember: This is the most important folder for your project, as it will hold the entire history of your project. Moving it is possible, but it requires more than just dragging it to a different location. Right-click this folder, and select 'TortoiseSVN --> Create Repository Here'. And voila! You should be getting a popup saying that the repository was successfully created. Now let's just make sure everything works: Let's assume your repository is at 'D:\Civ4\MyModRepository'. Go to the repo-browser as before, and type in the url: 'file:///D:/Civ4/MyModRepository'. Note the forward-slashes, and the fact that there are 3(!) of them before the drive letter. Spoiler : The 'file://' is the protocol used to access the repository, which means - just read the files from the disk. When using this protocol, you cannot have multiple users access safely to your repository, or to grant different access rights to different users. To do this, you need to start a SVN server on your machine, which is not complicated, but out of the scope of this guide. Back to business - now you should have the repo-browser dialog open on your newly created repository. You have probably noticed that it's empty. Let's create a folder for our project, and we'll call it, naturally, 'trunk': Right-click the main repository folder, and select 'Create folder'. Name it 'trunk' and click OK. What's that? Enter a log message? yes. Creating a folder is a change to the repository, and as such it gets its own revision. Each revision can have a log message. The log messages are for you and for anyone who might use the repository, so you can be as informative as you want to be. Or you can not write a log message. Your call. Now 'trunk' was added to the repository, and if you look at the log you'll see a single revision - in which you added a new folder. Setting up your project's working copy Next, we create a working copy for the repository. Choose a folder on which you'll work (In this tutorial I assume that this is an empty folder. We'll copy the files into it later). Right-click it, and select 'SVN checkout'. Make sure your repository's URL is entered at the top. Click the '...' button next to it. You repo-browser will open. Make sure the trunk folder is selected in the folders tree, and click OK. Make sure the 'Checkout directory' is the folder which you designated to be your working copy (most likely tortoise has added your repository name to it). Leave all other settings as default ('Fully Recursive', 'HEAD revision') and click OK. Your working copy is now checked out and ready to go! Other version control applications might have different meanings for checkout (e.g. lock the files you check out), but in SVN it means getting a local copy. You'll notice now that you have a small green 'V' sign on your folder icon in the explorer. That means that this folder contains no changes. We'll get to that later. You can right-click the folder, select 'TortoiseSVN -> Show Log', and see the log of the trunk folder of your repository. Spoiler : If you're interested, you can checkout the trunk of an existing Mod, such as BUG, the same way. Just make sure not to checkout the entire repository! In the repo browser just select the trunk folder, or any of its subfolders. A side note - to update your working copy with the changes made in the repository use 'SVN Update' from the context menu of the working copy folder. These can be changes made directly to the repository browser, from a different working copy you have or even changes made by other people. And one last side note - you might notice that the trunk folder (and every versioned folder inside it) has a hidden folder called '.svn' (or '_svn) . Do not touch this folder since it contains data which the Tortoise SVN needs! OK, time to put some content inside your project! Adding content The folder and content I create here are just an example. Your content might (and probably will) be different. I'll mention a few SDK-specific (DLL) notes later. We will perform a few steps: 1. Add the original files you work on Take the XML, python and C++ source code files you are about to modify, and place them inside the trunk folder in the same folder structure you want them to be stored. Use the original files you base your Mod on. For example: if you make modifications to the BTS 3.19 files, use them. If you base your Mod on BUG or another Mod - use the files from that Mod. The reason is so you can track the changes you have made to the files without mixing other modders' changes. Even if you already have a Mod of your own with changes you have made, it is a good idea to first add the original files so you can view your changes. Don't worry about forgetting a file. You can always add it later. To add a file to your working copy, right-click the file and choose TortoiseSVN->Add. The file will be marked as added (a little 'plus' sign will appear next to it): You can add multiple files at once by either selecting multiple files and right clicking or by right-clicking their containing folder. A dialog box will appear asking you which files you want to add: You can add a folder the same way you add a file. Add folders to your working copy in order to maintain your Mod structure. 2. Commit the original files you have added Note that what you did in step 1 was only adding the files to your local working copy. This is considered a local change. To actually have the files in the repository you need to commit this change. You can either commit each file or each group of files separately (by right-clicking a single file or multiple selected files), or by right clicking the trunk folder and committing all at once. In the commit dialog box you can select which changes you want committed. You will see a list of all the files you've added. You can (and probably should) add some comment in the text box, which will appear as a log message (try something informative like 'Added original files from BTS 3.19', or 'First step towards glory'). After committing, all the committed files and folders will be marked with a little green 'V' sign. 3. Make changes to the files in your working copy Open one of the files you've just added (which is marked with a green 'V') in your favorite editor, and make a small change to it. At this point, it doesn't really matter which (just add a letter, or press ENTER somewhere) and save the file. If you have already made modifications to files in your mod, you can just copy these files into the working copy, overriding the existing ones. Now look at the explorer window. Assuming you're at the correct folder, you'll see that the file has a little red exclamation mark next to it. This marks that the file has local changes that were not committed to the repository. If you go up one folder, you'll also note that its parent folder is marked as changed, and it's parent folder's parent folder is marked as changed, and so on until the trunk folder itself, which is also marked as changed. This makes it easy to see where in the working copy you have changes without actually having to go folder by folder and check. This will also happen if you add a file (as we did in step 1) - since it is considered a change, the added file's parent folder is considered to be changed. So what can you do with it? You can of course commit this file, as we've done with the files we've added. But you probably want to check what has changed first. Right-click the file, and select 'TortoiseSVN -> Diff'. The diff viewer will open and will compare between the version of the file which is in the repository and your local copy. Go over the toolbar buttons to see what you can do with this tool. Try going up one folder, right-click the parent folder and select 'TortoiseSVN -> Check for modifications'. A dialog box will open displaying a list of all changes made to the working copy of this folder, its sub folders and all of their files. Double click any modified file in the list to open the diff viewer for it. You can also use 'SVN Commit' to see all the local changes, just be careful not to commit something by accident. Right-click the file, either in this dialog box or in the explorer. You have now the 'revert' option, which means 'cancel all my local changes and go back to the version I've already committed'. This is a useful option, but you should be careful with it, so you won't lose your work. And this is most of the functionality that we needed - The ability to see which changes we've made and undo them. Well, at least the most recent ones. In the future I hope to show how you can undo something that you've already committed to the repository. Civ 4 SDK (DLL) specific notes To compile the DLL, you need to have all the files in the right place. In addition to the CvGameCoreDll files themselves, which you will probably modify, there are the Boost and Python files and folders. Adding these files to the repository is not a smart move, for two reasons. One is that there are thousands of source files and hundreds of folders in these libs. These will take a lot of space and might incur performance issues on the local caching which Tortoise SVN performs. The other is that these files never change (unless you are a truely professional modder...), which makes adding them to the repository pointless. So assuming you only work with one working copy (and yes, you can have more than just one), you can copy these files to the correct location in your working copy and not add them to your repository. To prevent them from appearing in different dialog boxes (especially when 'Show unversioned files' is checked), you can add these folders to the ignore list. Simply right-click the folder (e.g. Boost-1.32.0), select 'TortoiseSVN -> add to ignore list' and you will not have to worry about this folder again. You can also add other filters to your ignore list - files such as project user files, or .ncb files (the Visual Studio Intellisense cache), which you shouldn't add to your repository since they change frequently but have no importance for the Mod. Check your working copy ignore list in 'TortoiseSVN -> properties' when right clicking a folder. Plans for the future I don't want to make promises which I don't know if I can keep, but assuming I get to writing it, part II of this guide will describe the managing of different versions of the mod, different branches of the repository and merging code between versions, as well as reverting committed revisions.