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

Guide: Adding version control to your mod Using Tortoise SVN

Discussion in 'Civ4 - Modding Tutorials & Reference' started by Asaf, Sep 23, 2010.

  1. Asaf

    Asaf Sleep Deprived

    Joined:
    Mar 22, 2010
    Messages:
    1,326
    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.
     
  2. Asaf

    Asaf Sleep Deprived

    Joined:
    Mar 22, 2010
    Messages:
    1,326
    Part II - Versions, branches and merging

    Clarification: I use the term 'code' to describe the contents of the files in the repository. Of course the content can be anything else - XML files, readme files and even image files. Note however, that editing 'merge conflicts' (see below) is only available for text files.

    Versions
    Suppose you have created a great mod. Now you want to add a new feature to it. You just don't know if it will work that well. Or perhaps you know it will work well but it'll change the mod so much that some people might prefer to keep playing the old mod.

    Or maybe people are still finding bugs or request changes in your existing mod. And you'd probably want to give them fixes for it ASAP, and not wait for 3 months until you complete your next mod version.

    So how do you do that?

    Let's define the problem: you have version 1 of your mod, which is completed, but might need some minor fixing. And you want to create version 2, which is in development, and you'll make tons of changes to it. Version 2 should be based on version 1, and when you make changes to version 1 you want to be able to add them to version 2 as well.

    Branching
    Assuming you've been using TSVN up until now, you have a trunk folder which contains your current version (1) of the mod.
    What we're going to do is to create a new branch out of the trunk. You can imagine this as a tree of versions, where each branch can be split to other branches, and each branch's history also contains the history of its 'parent' branch up to the point where it was split from it (I hope this sentence made sense. If not, it soon will).
    By the way, this is where the name 'trunk' came from ;)

    We will place all of the branches for a specific mod in a special branches folder, so first create a folder named 'branches' (if you don't already have it) in the repo-browser, next to the trunk (usually you place it so they have the same parent folder).

    Since we want to keep the trunk as the main development branch, we will branch version 1 from it, and keep the trunk as version 2.
    One way to do it is this: Right-click your working copy folder, and choose 'TortoiseSVN --> Branch/tag'.

    You will get the following dialog:


    If you have local modifications in your working copy, you will get a warning, since we're going to branch from the repository and not from the working copy.

    To URL: Here we choose the path for the new branch. We will choose a folder for the branch under 'branches' and give it a meaningful name:
    Code:
    file::///D:/Work/svn/svn-repository/branches/MyMod-Ver-1
    
    The folder MyMod-Ver-1 will be created automatically in the repository.

    Create copy from: Next we choose the point in the repository from which we split the branch. We've already selected the path (the folder on which we right-clicked), now we need to select the point in its history:
    HEAD revision - means the last (newest) revision relevant for the origin branch. This is what we'll usually choose.
    Specific revision - we can branch from any point in the branch's history, according to the number of revision. clicking the '...' button will open the log so we can select a revision there.
    Working Copy - the branch will be made with the changes already in your working copy. Modifications will be committed to this new branch.

    Below is the log message, since branching is actually making changes to the repository and thus gets a revision of its own.
    For now leave the checkbox 'switch' unchecked.

    Clicking OK will create the new branch, which you can now see in the repo-browser.

    You can also create a new branch inside the repo-browser: right-click a folder and select 'Copy To'.

    Note that branching creates a copy in the repository, but it does not copy the data itself to the new branch. The branch 'remembers' where it came from, and will only save modifications made from here on, so you can create many branches with very little change to the actual size which the repository takes on the disk.

    If you look at the new branch's log, you might see only the latest revision in which you created the branch.
    This is because TSVN by default hides the history before the branching. To see the full history, uncheck the 'Stop on copy/rename' checkbox at the bottom of the Log dialog.

    Tags
    Technically speaking, in TSVN branches and tags are the same.

    Conceptually, tags are labels given to certain points in the repository. For instance, when you release a version of your mod (1.0), you want to be able to go back to its exact code.
    Branches are more dynamic than tags in the sense that you might want to commit additional changes to them.
    For example (this is similar to what appears in the beginning of this part): You have released version 1.0 of your mod, so you create a tag for it. You branch the code to a 'version 1' branch, and continue adding a new feature to the trunk (which will become version 2).

    But then someone finds a bug for your 1.0 version. So you fix the bug, commit it into 'version 1' branch, and create a new tag out of it - 1.1.
    You won't make any changes to these tags, since these are the exact code bases for your already released versions. Any changes are made to the branches.
    (I hope this is clear enough - let me know if something here is confusing and I'll try rewriting it)

    The only thing keeping branches and tags in TSVN apart is the way the user treats them - whether they are used for labeling a particular point, or they are used for ongoing development.
    It is common to add a 'tags' folder next to 'trunk' and 'branches' to hold all the labels you want for your project.

    Switching
    As mentioned before, you can have multiple working copies for the same repository, and even for the same branch. You create them using the 'checkout' option.
    You can, of course, have a working copy for each active branch - no need for a working copy for a branch you don't intend to work on anymore - But what if you just want to make a quick change and don't want to checkout the entire branch?

    The solution is to switch a working copy from one branch to another. You can do that in the context menu: right-click your working copy folder, 'TortoiseSVN --> switch', and you'll see the following dialog:


    Here you can change the point in the repository to which this working copy points. Again, you can specify non-HEAD revisions to point at any point in the history of the repository. TSVN will trace the repository tree all the way from the current point to the target point, and apply all the modifications to the working copy (some might be in reverse when going down a branch).
    It is advised that you'd have no local modifications, because this can cause conflicts when applying these modifications.

    If you don't remember where a working copy is pointing - open the repo-browser from its context menu and it'll point to its current position in the tree.

    Spoiler :

    Note that you can switch specific sub-folders (and even single files) to point at different locations in the repository. It can be quite confusing, so unless there's a good reason for it I'd advise against it.

    When creating a new branch, you can check the 'switch' checkbox, which in addition to the branching will cause the working copy to switch to the new branch.

    Merging
    Let's continue the previous scenario - you found the reported bug, and fixed it. You might have done it in either the trunk or the 'version 1' branch. Let's assume it was in the trunk, since this is what you were working on.
    First, to allow for semi-automatic merge, it's important to commit in the same revision only the things that you want to merge back to version 1 (nothing that is related to the new feature). The fix can be spread over several revisions, and you might want to fix several bugs.
    Just remember that what you merge is whole revisions.

    Now, we want to merge the changes back to version 1. For this we need to have working copy of version 1. This can be done either by checking it out to a new folder or by switching. Whatever is more comfortable to you.

    I will show here only one way of merging; there are other ways.

    Right-click the target working copy into which you want to merge the changes (in our example - Version 1's working copy), and select 'TortoiseSVN --> Merge'. You will get this dialog:


    Select 'Merge a range of revisions' and click 'Next'.
    You will get this dialog:


    In the 'URL to merge from' select the source of the merge, which is where you originally committed your revisions (in our example - the trunk).
    Again, you can use the '...' button to browse through the repository.

    Then select the revisions to merge. You can select any number of revisions and use commas as separators. You can use ranges and you can combiune them (e.g. "4,7,11-15,34"). But you don't have to. You can press the 'Show log' next to the 'revisions to merge' and select the revisions you want to merge there. Ctrl and shift will work here as well.

    Keep the 'Reverse merge' unchecked (it will be used for undoing revisions later).

    The second 'Show log' button is just to assist you if you want to be reminded of the history of the working copy.

    After you're done, click 'Next'. You'll get the following dialog:


    Leave the options as they are (Merge depth=Working copy, uncheck all checkboxes, compare whitspaces).
    You can click 'Test Merge' to see if the merge will go smoothly. It does not change the working copy.

    When you're done - click merge. All the revisions will be merged to the working copy.
    Note that you might get conflicts when merging. See the section about merging conflicts.

    Now you have the merged revisions as local modifications to the working copy, and all there is left to do is to commit them.
    Important: unless this is a VERY simple change, you should probably test that merge indeed worked properly (compile, run the game etc.).

    For more details on the merging process, see here.

    Merge tracking
    In addition to the merged files content, merging also modifies the properties of the parent folder into which you merge. After merging (but before committing) you can see it if you 'check for modifications'. You'll see the parent folder with 'Text Status' normal (not modified) but 'Property status' modified. Double clicking it will show you the changed properties.
    You should see there that the folder now 'remembers' which revisions were merged to it, and from where.
    Of course, this information will only be saved to the repository when you commit it.

    This information can be used in certain situations to protect you from multiple merging the same revision to the same branch. I will not go into it in this guide.

    Merging conflicts
    When the same code section was changed in the merged revisions in the target branch, you might get merging conflicts. This means that the auto-merge failed merging the code and requires you to manually decide how to merge.

    While the merging process runs, for each conflicted file you will get this dialog:


    Besides leaving the conflict for later (you will have a 'warning' icon overlay in explorer for the conflicted files), you have a few options:
    - Choose item: You can choose to keep one of the two whole files - the local copy (without the merged revisions), or the repository copy (the file with the merged revisions, but without the changes made to this branch). Then you can add the other file's changes manually.
    - Edit conflict: Will open the manual merge tool (see below). This is what you will usually want to do.
    - Abort merge - if the merge is simple enough, you might want to abort the entire merge, revert everything and add the changes manually.

    Assuming you have selected 'Edit conflict', you will see something similar to this:
    (The tool shown here is the default TortoiseMerge tool)


    In the tool's window you'll see 3 panels:
    On the top left panel, marked as 'Theirs', you'll see the file from the repository, and the changes made to it in the merged revisions are marked in colors according to the change (adding/deleting/modifying).
    On the top right panel, marked as 'Mine' you'll see the file from the working copy.
    On the bottom panel, marked as 'Merged' you'll see the attempted merged file with the merged revisions changes in colors.

    All changes which are marked in red are conflicted changes. You can browse through them using the red arrows in the top tool bar.
    You can select any number of text rows in any of the panels (shift might help here), right click the section and get the following options:
    - Use this text block: select this if you want to drop the matching rows in the other panel and use this only.
    - Use this whole file: Same as 'choose item' in the previous dialog.
    - use text block from X before Y: will add the selected sections in both panels one after the other.

    Additionaly, you can directly edit the merged file in the bottom panel.
    Don't forget to save your changes!

    After you're done (there are no more red sections anywhere) and saved the file, the file is not in conflict anymore. You can close the tool and press the 'Resolved' button in the 'Resolve conflict' dialog.

    Undoing revisions
    Undoing changes before committing them is easy - either use 'revert' or edit the files with the diff viewer.
    But what can you do after you've already committed your changes?

    You can use the 'reverse merge' feature.
    Follow the steps of merging, but in the 'URL to merge from' field select the same folder as the working copy's, and mark the 'reverse merge' checkbox.
    This will unmerge the revisions which were already committed to this branch.
    Again, this will only influence the working copy and you'll need to commit it if you want to undo the changes in the repository as well.

    Managing multiple mods
    I keep multiple mods in the same repository. Why do I do that? for two reasons:
    One - that way I can merge changes between mods (which can sometimes be useful), and two - I can create the same code base for all mods and branch out of it whenever I want to create a new mod. This is relevant mainly for SDK mods where even before you start modding you must have a few hundred files.

    A possible folder structure is this:

    Spoiler :

    Code:
    Repository
    |
    +--CodeBase
    |  |
    |  +--branches
    |  +--tags
    |  +--trunk
    |
    +--Mod1
    |  |
    |  +--branches
    |  +--tags
    |  +--trunk
    |
    +--Mod2
    |  |
    |  +--branches
    |  +--tags
    |  +--trunk
    


    That way, CodeBase's trunk holds all the C++ source files, projects, makefile etc., and when you want to create a new mod - you simply branch CodeBase to another branch, checkout that new branch's trunk folder and you can immediately start working.
    Of course you can add to the code base anything else you see fit - XML files, Python files, batch files, readme etc.

    Exporting files
    If you want to get entire folders from the working copy (e.g. the Assets folder) but don't want to copy and then manually delete all those pesky .svn folders, you can use this option:
    Right-click the folder you want to export, 'TortoiseSVN --> Export', select a target folder, and it's done.

    More information
    A more complete (and official) guide can be found here.
     
  3. Asaf

    Asaf Sleep Deprived

    Joined:
    Mar 22, 2010
    Messages:
    1,326
    Reserved yet again
     
  4. LyTning94

    LyTning94 Dragonborn

    Joined:
    Nov 10, 2010
    Messages:
    397
    Location:
    Skyrim
    I just finished reading your guide and setting up Tortoise SVN. THANK YOU for writing such an amazing guide! :king:

    I was curious, however, if you are ever planning on writing the part 2 you mentioned at the end. The topics you mentioned would be very helpful, and I'm sure plenty of inexperienced modders like me would gain a lot from it :D. If not, do you know of another (even non-Civilization) guide that would cover some of these topics?
     
  5. Asaf

    Asaf Sleep Deprived

    Joined:
    Mar 22, 2010
    Messages:
    1,326
    Thanks! I'm glad it helped you.

    Sure, I'll write the 2nd part now that there's interest.
    Expect an update in the next few weeks...
     
  6. Asaf

    Asaf Sleep Deprived

    Joined:
    Mar 22, 2010
    Messages:
    1,326
  7. LyTning94

    LyTning94 Dragonborn

    Joined:
    Nov 10, 2010
    Messages:
    397
    Location:
    Skyrim
    Thanks once again! :king:
     
  8. Thunderbrd

    Thunderbrd C2C War Dog

    Joined:
    Jan 2, 2010
    Messages:
    24,867
    Gender:
    Male
    Location:
    Las Vegas
    oi vay! Do I know how to make a mess or what?

    I got stuck here... yeah, got real far ;)
    I selected the working folder that I had compiled my last dll from. It was based on Afforess's source files and it seemed to remember that because when I went to perform the next steps, nothing was like as it appeared in the tutorial, which of course had me trying to troubleshoot my way past it before I understood fully what was going on. I went about it in some forgotten manner, and ended up setting the main, not the trunk as the file head, which, I can't seem to undo or switch...
     
  9. Asaf

    Asaf Sleep Deprived

    Joined:
    Mar 22, 2010
    Messages:
    1,326
    Don't worry about it, I've created some big messes when I started working with it :lol:

    It appears that I need to somewhat clarify it in the tutorial - in this tutorial I assume that you perform the checkout on an empty folder, and that's why you have instructions later on adding the files.
    It can also be done the way you did it, but I didn't think of this way when I wrote the tutorial...

    You can completely disconnect the folder from the repository by deleting the '.svn' folder in each folder and sub-folder which has it.

    Then try again on an empty folder.

    Let me know how it works out (feel free to ask more questions :))
     
  10. ripple01

    ripple01 Chieftain

    Joined:
    Mar 7, 2006
    Messages:
    1,246
    Location:
    New York City
    Many thanks for this. I tried to setup a TortoiseSVN a while back and couldn't quite figure it out. I'm going to take another stab at it using your tutorial.
     
  11. Asaf

    Asaf Sleep Deprived

    Joined:
    Mar 22, 2010
    Messages:
    1,326
    You're welcome and good luck. Hope it works out :)
     
  12. kiwitt

    kiwitt Road to War Modder

    Joined:
    Jan 11, 2006
    Messages:
    5,547
    Location:
    Auckland, NZ (GMT+12)
    Wow ... This will be great.

    I have currently two mods I am working on. Well really three
    Road to War - Original by Dale
    Road to War - Historical
    Road to War - Historical SP1

    Should I create a new folder called "C:\DEV\CIV4\RoadtoWar" for my repository.

    I can then copy the "original" first into this folder, then add my Historical files and then add my SP1 files ?
     
  13. Asaf

    Asaf Sleep Deprived

    Joined:
    Mar 22, 2010
    Messages:
    1,326
    Sorry for the long delay, I was away from my computer.

    You can use a single repository for all your mods.

    If you have different mods which you intend to keep different, use different branches in the same repository for them (just create a different folder in the repository for each).

    If they have the same base - you can create this base in a working folder, commit it to the repository, and then from it branch the different mods you need.

    Either way, you can checkout each of these branches to a separate folder and have a separate working copy for each.
     
  14. kiwitt

    kiwitt Road to War Modder

    Joined:
    Jan 11, 2006
    Messages:
    5,547
    Location:
    Auckland, NZ (GMT+12)
    So on your suggestion, I could have

    ...\RoadtoWar
    ...\RoadtoWar\The Road to War
    ...\RoadtoWar\The Road to War - Historical
    ...\RoadtoWar\The Road to War - Historical SP1

    However, I have nearly finished SP1 the old way ... So will use this method when I work on version 1.2
     
  15. Asaf

    Asaf Sleep Deprived

    Joined:
    Mar 22, 2010
    Messages:
    1,326
    Assuming you're talking about your folder structure, and that each sub folder is a working copy which points to another branch in the repository - then yes, that's what I meant.
     
  16. Thunderbrd

    Thunderbrd C2C War Dog

    Joined:
    Jan 2, 2010
    Messages:
    24,867
    Gender:
    Male
    Location:
    Las Vegas
    Ok, my question:

    Do you know of any good sites or methods to host an SVN online for multiple parties to work on?
     
  17. Asaf

    Asaf Sleep Deprived

    Joined:
    Mar 22, 2010
    Messages:
    1,326
    If you want free services over the internet, you can use sourceforge or Google's, but they're both (AFAIK) for open source projects, so you can't limit read access (I think).
     
  18. ripple01

    ripple01 Chieftain

    Joined:
    Mar 7, 2006
    Messages:
    1,246
    Location:
    New York City
    Hey Asaf, I just want to thank you again for this guide. I was able to successfully set up a repository for my mod following your instructions. Good work!
     
  19. Thunderbrd

    Thunderbrd C2C War Dog

    Joined:
    Jan 2, 2010
    Messages:
    24,867
    Gender:
    Male
    Location:
    Las Vegas
    Thanks! I'll look into those links further then.
     

Share This Page