WildWeazel
Carthago Creanda Est
Do your .biq files keep disappearing, costing weeks of work? Do you make changes to text files that break your mod, only to find that you can't remember what you changed? Do you wish you could undo that last set of changes without doing it all manually? If so, then this tutorial is for you. I'll show you how to manage your files with version control so that you can easily track and go back to previous changes.
Subversion (svn) is a software version control system that developers use to maintain revisions of source files. It provides many functions including versioned file backups, revision history, branching and merging change sets, and more. For this tutorial I will be using the free Subversion client program TortoiseSVN (TSVN) on Windows and focusing on basic configuration and backup for Civ3 mods. TSVN can do a lot more than what I'm covering here, but the basic commit/update/revert features are enough for most purposes.
Part 1: Putting your files into a repository
First, you will need to download and install the latest version of TortoiseSVN in the language of your choice. For the sake of brevity I'll let you work that part out yourself. The complete TortoiseSVN manual is available online. You can refer to it for features that we don't cover here.
Once you have TSVN installed, you need to create a repository. A repository is a folder containing a database that will store your file history. Choose a location for your repository (it can be anywhere, but remember the location) and create a new, empty folder there called "SVN". Right-click on the new folder (from where you created it, not from inside it). You should now see TSVN options appear in your context menu. In most locations, it will look like this:
Select "Create repository here." TSVN will indicate that a new repository has been created. Take a look inside if you'd like, but don't touch anything. You should never make any modifications directly to this folder or the files inside. All changes will be made through the TSVN program.
Now that you have a repository, you're ready to add your Scenarios directory so that TSVN can manage it. Now you don't necessarily want to put your Scenarios at the root of the repository since you may have other things to import later, so make a directory just for your mods. From the TortoiseSVN menu, select Repo Browser. The browser is a very useful tool that allows you to view the repository contents as if it were a normal file system. Any time you want to view the files as they exist in your repository, you'll use the Repo Browser. TSVN will ask you which repository you want to view. If it's not already there, enter the location of the repository you just created, prefixed by file:/// and with forward slashes (/) and click OK.
You'll see that there is nothing in your new repository yet. Now to make a location for your Scenarios.
Right-click on the root folder at the left and create a new folder called "Civ3 Scenarios". You have the option to include a comment with this and every other action that modifies repository contents. You can skip the comment for now. Your repository now includes a single folder, "Civ3 Scenarios". Now you have a place to store your Scenarios. Click OK to close the browser.
Now that you have an empty "Civ3 Scenarios" directory in your repository, you need to map your local Scenarios folder to it. There are a few ways to get a local folder synched with TSVN. In general you would create a new folder, import it to the repository, and then start adding files. But you already have a folder full of mods, and you're probably not interested in managing all of them with TSVN. So you're going to do an "import in place" which is just a little more complicated.
Next go to your Scenarios folder, right-click, and select "SVN Checkout...". From this window, select the Civ3 Scenarios directory that you just created at the URL of repository. Then remove "Civ3 Scenarios" which was automatically appended to the Checkout directory so that it points directly to your existing Scenarios folder. You're checking out an empty folder on top of an existing one, which effectively converts the folder into a checked-out copy of your repository directory. Ignore the other setting this time. Click OK, then Yes at the warning to indicate that you do want to check out into a folder that is not empty.
TSVN will check out the contents of "Civ3 Scenarios", which is at this point nothing, on top of your Scenarios folder. Now your Scenarios folder is a checked-out copy of your repository directory. If you have hidden files visible, you'll see that this folder and each sub-folder now has a hidden folder ".svn" which stores metadata about their contents. Don't touch them.
By the way, now that you're working in a checked-out folder, the TSVN menu contains many more features. We won't be using most of them in this tutorial, but you can check out the manual if you're interested in learning more.
Now you need to add your mod files to the repository. The only problem is, when you made this a checkout location, everything was automatically tagged as belonging to the repository. So first you need to tell TSVN to ignore anything that you don't want to manage, such as third-party mods that you don't modify.
Let's say you have a mod MyMod that you want to manage with TSVN, but you don't care about Some Random Mod that you downloaded from CFC. Right-click on the BIQ for Some Random Mod. Under TSVN, select "Add to ignore list > Some Random Mod.biq". Repeat this for each file and/or top-level folder in Scenarios that you do not want to manage with TSVN. You can hold Ctrl to select multiple items, then choose "Add to ignore list > Ignore X items by name".
Now you're ready to commit your mod to the repository. Right-click in the folder (not on a file) and select "SVN Commit...". This is how you will push file updates into the repository for backup. Make sure that only the files for the mods you want to manage are listed, then click "Select / deselect all" below the list to select all of them. Write a brief comment to indicate that this is your first commit. Whenever you make a commit to the repository, it's always helpful to include a comment so that you can tell later what you did in case you need to go back to a previous revision.
Click OK and wait for TSVN to complete the commit.
Congrats! You now have a mod under revision control in your repository. You can view the Repo Browser again to see the file structure that has been created. It looks exactly like your local copy, but only includes the files that were committed.
This completes Part 1. In Part 2 you will learn how to commit and track incremental changes, and roll them back when you make a mistake.
Subversion (svn) is a software version control system that developers use to maintain revisions of source files. It provides many functions including versioned file backups, revision history, branching and merging change sets, and more. For this tutorial I will be using the free Subversion client program TortoiseSVN (TSVN) on Windows and focusing on basic configuration and backup for Civ3 mods. TSVN can do a lot more than what I'm covering here, but the basic commit/update/revert features are enough for most purposes.
Part 1: Putting your files into a repository
First, you will need to download and install the latest version of TortoiseSVN in the language of your choice. For the sake of brevity I'll let you work that part out yourself. The complete TortoiseSVN manual is available online. You can refer to it for features that we don't cover here.
Once you have TSVN installed, you need to create a repository. A repository is a folder containing a database that will store your file history. Choose a location for your repository (it can be anywhere, but remember the location) and create a new, empty folder there called "SVN". Right-click on the new folder (from where you created it, not from inside it). You should now see TSVN options appear in your context menu. In most locations, it will look like this:
Select "Create repository here." TSVN will indicate that a new repository has been created. Take a look inside if you'd like, but don't touch anything. You should never make any modifications directly to this folder or the files inside. All changes will be made through the TSVN program.
Now that you have a repository, you're ready to add your Scenarios directory so that TSVN can manage it. Now you don't necessarily want to put your Scenarios at the root of the repository since you may have other things to import later, so make a directory just for your mods. From the TortoiseSVN menu, select Repo Browser. The browser is a very useful tool that allows you to view the repository contents as if it were a normal file system. Any time you want to view the files as they exist in your repository, you'll use the Repo Browser. TSVN will ask you which repository you want to view. If it's not already there, enter the location of the repository you just created, prefixed by file:/// and with forward slashes (/) and click OK.
You'll see that there is nothing in your new repository yet. Now to make a location for your Scenarios.
Right-click on the root folder at the left and create a new folder called "Civ3 Scenarios". You have the option to include a comment with this and every other action that modifies repository contents. You can skip the comment for now. Your repository now includes a single folder, "Civ3 Scenarios". Now you have a place to store your Scenarios. Click OK to close the browser.
Now that you have an empty "Civ3 Scenarios" directory in your repository, you need to map your local Scenarios folder to it. There are a few ways to get a local folder synched with TSVN. In general you would create a new folder, import it to the repository, and then start adding files. But you already have a folder full of mods, and you're probably not interested in managing all of them with TSVN. So you're going to do an "import in place" which is just a little more complicated.
Next go to your Scenarios folder, right-click, and select "SVN Checkout...". From this window, select the Civ3 Scenarios directory that you just created at the URL of repository. Then remove "Civ3 Scenarios" which was automatically appended to the Checkout directory so that it points directly to your existing Scenarios folder. You're checking out an empty folder on top of an existing one, which effectively converts the folder into a checked-out copy of your repository directory. Ignore the other setting this time. Click OK, then Yes at the warning to indicate that you do want to check out into a folder that is not empty.
TSVN will check out the contents of "Civ3 Scenarios", which is at this point nothing, on top of your Scenarios folder. Now your Scenarios folder is a checked-out copy of your repository directory. If you have hidden files visible, you'll see that this folder and each sub-folder now has a hidden folder ".svn" which stores metadata about their contents. Don't touch them.
By the way, now that you're working in a checked-out folder, the TSVN menu contains many more features. We won't be using most of them in this tutorial, but you can check out the manual if you're interested in learning more.
Now you need to add your mod files to the repository. The only problem is, when you made this a checkout location, everything was automatically tagged as belonging to the repository. So first you need to tell TSVN to ignore anything that you don't want to manage, such as third-party mods that you don't modify.
Let's say you have a mod MyMod that you want to manage with TSVN, but you don't care about Some Random Mod that you downloaded from CFC. Right-click on the BIQ for Some Random Mod. Under TSVN, select "Add to ignore list > Some Random Mod.biq". Repeat this for each file and/or top-level folder in Scenarios that you do not want to manage with TSVN. You can hold Ctrl to select multiple items, then choose "Add to ignore list > Ignore X items by name".
Now you're ready to commit your mod to the repository. Right-click in the folder (not on a file) and select "SVN Commit...". This is how you will push file updates into the repository for backup. Make sure that only the files for the mods you want to manage are listed, then click "Select / deselect all" below the list to select all of them. Write a brief comment to indicate that this is your first commit. Whenever you make a commit to the repository, it's always helpful to include a comment so that you can tell later what you did in case you need to go back to a previous revision.
Click OK and wait for TSVN to complete the commit.
Congrats! You now have a mod under revision control in your repository. You can view the Repo Browser again to see the file structure that has been created. It looks exactly like your local copy, but only includes the files that were committed.
This completes Part 1. In Part 2 you will learn how to commit and track incremental changes, and roll them back when you make a mistake.
