1. We have added a Gift Upgrades feature that allows you to gift an account upgrade to another member, just in time for the holiday season. You can see the gift option when going to the Account Upgrades screen, or on any user profile screen.
    Dismiss Notice

Tutorial: Managing your mod files with Subversion

Discussion in 'Civ3 - Tutorials, Reference, & Guides' started by WildWeazel, Aug 27, 2011.

  1. WildWeazel

    WildWeazel Space Race Victory Supporter

    Joined:
    Jul 14, 2003
    Messages:
    6,935
    Location:
    %CIV3%\Conquests\Scenarios\
    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.
     
  2. WildWeazel

    WildWeazel Space Race Victory Supporter

    Joined:
    Jul 14, 2003
    Messages:
    6,935
    Location:
    %CIV3%\Conquests\Scenarios\
    Part 2: Committing, browsing, and reverting changes

    In the first post I showed you how to set up a repository and import your mod files to it. Now I'm going to walk through some contrived changes to my own mod files so that you can see how to keep your repository up-to-date and look back at the changes you've made.

    Here we are at my Conquests scenarios directory. If you don't see your mod in there, my apologies- this machine is less than a year old and I haven't gotten around to installing all of them yet ;)



    The few green checks identify those files at a glance as being under source control. Let's see what I've been doing with them. Right-click somewhere in the folder and select TortoiseSVN > Show Log



    There you go. As you can see, I haven't been very busy in here. In fact, I made a couple of commits just for the purpose of illustration. But no matter how long ago it was, there is every change I've committed to this branch of the repository, with a date and comment. Unless you've gotten ahead of me already, you probably only see a single revision- your initial import. You can also view the log of a particular folder or file, but for now we're interested in the whole project.

    Go ahead and make some changes, so you have something to work with. It can be anything- we're about to undo it anyway. Just open a file or two, change something, and save. That represents a day's work on your mod. You'll see that as you save changes, the file's icon will change from green to red, indicating that it's out of synch with the repository. It's time to commit your daily change set. Go back up to Scenarios, if you're not already there, and select "SVN Commit..." like you did when you imported your projects. TSVN will scan files, then show you a list of all changed files that are under source control in this folder and any sub-folders. It should show only the files that you just changed, because you told it to ignore everything else.



    Before committing, you can review the files that have been changed. Double-click on any of the listed files to open them in TortoiseMerge. This enhanced text editor shows you two files (or in this case, two copies of a file) side-by-side with the differences highlighted. This is very useful for tracking individual changes to a file across revisions. TortoiseMerge won't work for binary files like graphics and BIQs, but you can still view their file logs and open individual past versions.

    Now go back to the commit dialog and write a short message describing what you changed. That helps you track changes later when you're looking through the log. You'll notice that if you start to type the name of a changed file, it will be suggested for you. When you've reviewed your changes, click OK and wait for the commit to complete.

    Oops! It looks I've made a regrettably short-sighted change and I've already committed it. What's worse, I've made additional changes to that same file afterwards. How will I ever get those changes sorted out? No problem, let's head to the log and take a look:



    There's the offending change, Rev.17. I removed some lines from PediaIcons.txt and now my mod is crashing. That commit also included some other files, and Rev.18 also included further changes to PediaIcons.txt. Fortunately, those changes were in separate parts of the file, so it's an easy fix. (Overlapping changes can be fixed too, but it takes some manual work in TortoiseMerge that is beyond the scope of this tutorial.)

    In a real scenario, it might not be so easy to determine which revision needs to be undone. If you're not sure which revision you're looking for, you can double-click on any of the file names listed below to open TortoiseMerge with that revision and the previous one to see only the changes made at that point. Alternatively, you can choose "Blame..." to view composite changes over a range of revision. Each set of changes will be highlighted with the corresponding revision number. That's a good way to find out when a particular change was made.

    Changes need to be undone, so a Revert is in order. Right-click on the revision you want to change. There are a few useful things we could do here. "Compare with working copy" would open TortoiseMerge and show you a composite of all changes that have been made between that revision and your working copy. "Revert to this revision" would roll back to a committed revision and discard all later changes. "Revert changes from this revision" would get rid of a change that's already been committed and keep later changes. That one sounds like what we want, but we're only concerned with one file in this case. So select the file in the list below and do your revert from there. After you have reverted your changes (say Yes at the warning) click OK to close the log.

    Now go find your reverted file and select TortoiseSVN > Diff. This will open TortoiseMerge again, showing the difference between the latest committed revision (left) and your newly reverse-merged working copy (right) of the offending file. As you can see, the missing lines have been replaced. And in my case, the changes that I had made since are still there, so there's no need to go redoing my later work.



    Now that you've verified the fix, commit your file again with a message indicating that you have reverted the previous change. It's important to note that despite your revert you haven't modified the revisions that were already committed- your mistaken change is still there in the log. The undoing of the revision was only applied to your working copy, and now you're using that copy to once again create a new revision.



    Easy, right? If you made a mistake but haven't committed the changes yet, it's even simpler. Right-click in the folder and select Revert. TSVN will show a list of any versioned files that don't match the head revision. Select the ones you want to revert and click OK. TSVN will discard any changes and replace them with the latest committed revision.



    Now you've made changes, committed them to the repository, and reverted (to) previous revisions. That's basically all you need to know to start managing your mods. Remember to make small, frequent commits and use comments to help you track your changes.
     
  3. WildWeazel

    WildWeazel Space Race Victory Supporter

    Joined:
    Jul 14, 2003
    Messages:
    6,935
    Location:
    %CIV3%\Conquests\Scenarios\
    Part 3: Updating, merging, and exporting

    I'll expand on this part later, but for now you should know that you can Export a directory from your repository to create a new copy that is not under source control. You'll want to do this as a last step before uploading a mod, so that it won't include all the .svn folders.
     
  4. nick0515

    nick0515 Fantasy World Builder

    Joined:
    Jan 5, 2008
    Messages:
    2,510
    Gender:
    Male
    Location:
    New Zealand
    Thanks WildWeazel, this looks very useful. I've stuffed up things many times before and it will be great to always have a back-up of files to revert too.
     
  5. Supa

    Supa Out of Cheese Error

    Joined:
    Jan 7, 2003
    Messages:
    3,663
    Location:
    Belgium
  6. Blue Monkey

    Blue Monkey Archon Without Portfolio

    Joined:
    Jul 31, 2005
    Messages:
    11,188
    Location:
    Timeless Isle
    Now that we've got an editor for other platforms if anyone knows of a similar product - especially for OSX - it will be deeply appreciated.
     
  7. WildWeazel

    WildWeazel Space Race Victory Supporter

    Joined:
    Jul 14, 2003
    Messages:
    6,935
    Location:
    %CIV3%\Conquests\Scenarios\
    Blue Monkey: You could try the Collabnet community client. I've never used it, but being a Subversion client it should have similar features.
     
  8. WildWeazel

    WildWeazel Space Race Victory Supporter

    Joined:
    Jul 14, 2003
    Messages:
    6,935
    Location:
    %CIV3%\Conquests\Scenarios\
    Part 2 is posted!
     

Share This Page