Guide: Setting up source control for Battlefront mods (SVN)

In this forum you will find and post information regarding the modding of Star Wars Battlefront 2. DO NOT POST MOD IDEAS/REQUESTS.

Moderator: Moderators

Post Reply
Marth8880
Resistance Leader
Posts: 5042
Joined: Tue Feb 09, 2010 8:43 pm
Projects :: DI2 + Psychosis
Games I'm Playing :: Silent Hill 2
xbox live or psn: Marth8880
Location: Edinburgh, UK
Contact:

Guide: Setting up source control for Battlefront mods (SVN)

Post by Marth8880 »

Hey everyone! After months and months of putting it off, I've finally decided to write a guide on how to set up source control for Battlefront mods! Let's get started.


What is source control?

Conveniently, there already exists a relatively quick video explaining this so please check that out first and foremost, even if you're not interested in the subjectmatter:



In short, source control allows you to keep a complete revision history of your projects (kind of like what Google Docs and OneDrive/Office provide), which is extremely, insanely useful in case you ever run into problems with your project - problems like, for example, if you can't get something to munge no matter what you try. If that happens and you're not set up with source control, you're essentially screwed and forced to work backwards manually, which costs a significant amount of time, pain, and frustration. However, if you have source control set up and you've been good about regularly committing changes, you can simply roll back the relevant file(s) to the last working revision.

Another extremely powerful aspect of source control is that it enables collaboration between 2 or more people. This requires a bit more setup if you use a cloud solution like GitHub or Bitbucket, and even more setup if you're hosting the repository locally and supporting remote access like I do, but they're options nonetheless.

"But it's just casual modding, Marth!"

Yes and? That literally could not be less relevant. Unless you're completely 1000000% fine with the possibility of losing all of your work, you seriously need to start using source control.


Great! How do I get started?

I'm glad you asked! Firstly you'll need to choose a source control solution, such as Subversion or Git. Personally, for Battlefront mods, I prefer Subversion because it's better (than Git) with handling large binary files. With that said, this guide is going to revolve around Subversion.

First and foremost, you'll need to install a Subversion client. I use TortoiseSVN because of its fast and easy shell integration, seeing as how it enables you to do everything via a Windows Explorer context menu.

You can download TortoiseSVN HERE. Simply run the installer and you'll be good to move forward!


Setting up a local repository

As the video explained, a project's revision history (log messages AND actual file changes) is stored in what's called a "repository"; files inside the repository should never be manually modified by you, doing so could corrupt the repository.

To be able to make changes to the repository, you need to "checkout" your own "working copy" of the repository. From there, the basic flow is: make your changes in your working copy, then commit those changes (with a simple changelog) back to the repository.

NOTE: In the context of Battlefront mods, the working copy would act as your mod's data_*** folder.


Create the repository

Now that the workflow is covered, let's learn how you create a repository in the first place. Here are the steps to do so:
  • 1. Determine where you want the repository to be located on your computer. I recommend keeping it in your newest drive with the most free space. Once you've chosen a location, create a new folder for the repository and name it something that makes sense, like "data_ABC".

    2. Inside of your repository's new, empty folder, right-click anywhere in the Explorer window and select 'TortoiseSVN > Create repository here'.
    Hidden/Spoiler:
    Image
    3. Shortly after, a window will pop up saying the repository has been created. When it pops up, it'll have automatically highlighted the URL to the repository; copy this URL to your clipboard, click "Create Folder Structure", then click OK.
    Hidden/Spoiler:
    Image

Checkout your working copy

Next we're going to checkout the initial working copy of the repository.
  • 1. Navigate to your 'BF2_ModTools' directory. If you're setting up source control with an existing mod project folder, rename that project folder to something temporary, like "data_ABC2". If you're setting up source control for a new mod project, use VisualMunge to create the mod project folder now, and rename project folder once it's done.

    2. In the 'BF2_ModTools' directory, right-click anywhere in the directory and select 'SVN Checkout...'.
    Hidden/Spoiler:
    Image
    3. In the Checkout window, paste the repository's URL in the 'URL of repository' field, ensure that the 'Checkout directory' field matches the directory in which you want your working copy to be located - make sure it ISN'T just the 'BF2_ModTools' directory root (e.g., "J:\BF2_ModTools") - and click OK.
    Hidden/Spoiler:
    Image
    4. In 'BF2_ModTools', select your mod project's folder (which you temporarily renamed), right-click, and select 'Cut'.

    5. Go into the 'data_ABC' folder. In it you should see 3 folders: 'branches', 'tags', and 'trunk' - and also '.svn' if you have hidden files enabled. Then go into the 'trunk' folder, right-click, and select 'Paste'.

    6. Go back into 'BF2_ModTools', select the 'ToolsFL' folder, right-click, and select 'Copy'. Then go back into the 'trunk' folder, right-click, and select 'Paste'. The 'trunk' folder should contain your temporarily-renamed mod project folder and the 'ToolsFL' folder.

    7. Rename your temporarily-renamed mod project folder back to what it was previously; the 'trunk' directory should now look like this:
    Hidden/Spoiler:
    Image

Configure the repository to ignore munged files/etc.

Now that our working copy has been checked out, we're going to configure what are called "ignores". These tell Subversion to ignore files and folders whose names match the filters set up in the ignores, which can include things like folder/file name or extension. In our case, we want to ignore munged files, log files, the '_LVL_PC' directory, and a couple files that are auto-generated by Zero Editor.
  • 1. Navigate to 'BF2_ModTools\data_ABC\trunk', right-click, and select 'TortoiseSVN > Properties'. In the Properties window, select 'New... > Other'.
    Hidden/Spoiler:
    Image
    2. In the 'Property name' field, type or select "svn:global-ignores" from the dropdown.
    Hidden/Spoiler:
    Image
    3. Paste the following in the 'Property value' field:
    Hidden/Spoiler:
    [code]*.bnk
    *.boundary
    *.class
    *.config
    *.congraph
    *.envfx
    *.files
    *.font
    *.light
    *.loc
    *.lvl
    *.model
    *.path
    *.povs
    *.prop
    *.script
    *.shader
    *.sprite
    *.str
    *.terrain
    *.texture
    *.world
    *.log
    *.au
    *.aup
    *.mvs
    *.sfk
    *.zmd
    [/code]
    4. Check 'Apply property recursively', click OK, then click OK in the Properties window.
    Hidden/Spoiler:
    Image
    5. Right-click the 'BF2_ModTools\data_ABC\trunk\data_ABC' folder and select 'TortoiseSVN > Add...'.

    6. In the Add window, uncheck 'Select / deselect all'. Then check 'data_ABC' and 'data_ABC\_BUILD'; those two items should be the ONLY items checked in the entire file list. After that's done, click OK, and click OK in the results window.
    Hidden/Spoiler:
    Image
    7. Navigate to 'BF2_ModTools\data_ABC\trunk\data_ABC', right-click, and select 'TortoiseSVN > Properties'. In the Properties window, select 'New... > Other'.

    8. In the 'Property name' field, type or select "svn:ignore" from the dropdown.

    9. Paste the following in the 'Property value' field:
    Hidden/Spoiler:
    [code]_LVL_PC
    journal.dat
    [/code]
    Hidden/Spoiler:
    Image
    10. Click OK, then click OK in the Properties window.

    11. Navigate to 'BF2_ModTools\data_ABC\trunk\data_ABC\_BUILD', right-click, and select 'TortoiseSVN > Properties'. In the Properties window, select 'New... > Other'.

    12. In the 'Property name' field, type or select "svn:ignore" from the dropdown.

    13. Paste the following in the 'Property value' field:
    Hidden/Spoiler:
    [code]*.req
    *.txt
    *.log
    *.anims
    *.zaabin
    *.zafbin
    [/code]
    14. Check 'Apply property recursively', click OK, then click OK in the Properties window.

Perform the initial commit

Now that the ignores are configured properly, we can finally perform our initial commit!
  • 1. Navigate to 'BF2_ModTools\data_ABC\trunk', select all of the folders inside, right-click, and select 'TortoiseSVN > Add...'.

    2. In the Add window, select all of the files and folders and click OK.
    Hidden/Spoiler:
    Image
    ** Please note that it may take a minute or more for the results window to pop up after the Add window disappears. **

    3. Once it's finished Adding, click OK.

    4. Navigate to 'BF2_ModTools\data_ABC', right-click, and select 'SVN Commit...'.

    5. In the 'Message' field, type a changelog message like "Initial assets commit" and click OK.
    Hidden/Spoiler:
    Image
    ** Please note that this will take some time to complete. If TortoiseSVN crashes for whatever reason, perform steps 4-5 again but only commit a single directory of files in 'trunk\data_ABC' at a time. **

How to revert a file to a previous revision

To revert a file(s) to a previous revision: right-click the file in Explorer, select 'TortoiseSVN > Update to revision...', enter the revision number in the 'Revision' field, and click OK.
  • If you don't know the revision number, click the 'Show log' button in the Update To Revision window or do 'TortoiseSVN > Show log' on the file in Explorer. This will bring up the Log, which contains the revision history; the number you want is in the 'Revision' column of the revision list.
  • To revert back to the latest revision, right-click the file in Explorer and select 'SVN Update'.

Important notes
  • When you want to add new files/folders to the repository, you must 'SVN Add' the files/folders. This is easy to do: simply right-click the files/folders, select 'TortoiseSVN > Add...', and follow the prompts as usual.
  • In order to delete a file/folder from the repository, you must do so with 'SVN Delete'. This process works pretty much the same as 'SVN Add'. If you try deleting a file the normal way (selecting the file and pressing the delete key on your keyboard), the file will be restored when you SVN Update.
  • SVN operations performed from the Explorer context menu only apply to files in the directory tree of the folder that the operation was performed from. For example, if I made changes to files in data_ABC and in data_ABC\Sides\REP and I begin an 'SVN Commit' operation from data_ABC\Sides\REP, only the changes in data_ABC\Sides\REP and its child folders will show up in the Commit window.

Workflow and best practices
  • As is detailed HERE, the general workflow should be the following:
    • 1. Update your working copy
      • SVN Update
      2. Make changes
      • SVN Add
      • SVN Delete
      • SVN Copy
      • SVN Move
      3. Examine your changes
      • SVN Status
      • SVN Diff
      • SVN Revert
      4. Merge others' changes
      • SVN Merge
      • SVN Resolved
      5. Commit your changes
      • SVN Commit
  • You always need to enter a commit message no matter what, no exceptions. This will help you to see what happened and when, as you browse through the project log messages at a later date. They don't have to be long or super-detailed, just a short and sweet summary of what was changed, e.g., "Increased thermal detonator explosion damage" or "Fixed issue #1138: resolved missing entity reference in line 42". If you have a small list of changes, break it up into a hyphenated list like so:

    Code: Select all

    - Changed X blah
    - Changed Y blah blah
    - Changed Z blah blah blah
  • If you ever forget what you've changed in a text file, you can diff (i.e., compare differences) your working copy of the file with the previous revision (or any revision) using TortoiseMerge, which comes with TortoiseSVN. You can start a diff by right-clicking a file and selecting 'TortoiseSVN > Diff later/with previous revision'; by double-clicking a file in the Commit window; or by simply launching the TortoiseMerge application from the Start Menu.
  • The rule of thumb for working with source control is to keep your work focused and commit often. What this means is to not work on a ton of vastly different things at once and then commit the changes after a huge chunk of work has been completed - instead, work on a single pass of a certain feature or a single bug at a time, and then commit the changes for that thing.

Help

If you need further help with Subversion, TortoiseSVN, general source control things, etc., feel free to drop a message in this thread, PM me here or on Discord, or consult TortoiseSVN's exhaustive help documentation, which is found in its Start Menu folder.
Last edited by Marth8880 on Sun Mar 11, 2018 6:33 am, edited 1 time in total.
User avatar
Anakin
Master of the Force
Master of the Force
Posts: 4817
Joined: Sat Sep 19, 2009 11:37 am
Projects :: RC Side Mod - Remastered - SWBF3 Legacy
Location: Mos Espa (germany)

Re: Guide: Setting up source control for Battlefront mods

Post by Anakin »

Nice tutorial. But why svn and not git?
Marth8880
Resistance Leader
Posts: 5042
Joined: Tue Feb 09, 2010 8:43 pm
Projects :: DI2 + Psychosis
Games I'm Playing :: Silent Hill 2
xbox live or psn: Marth8880
Location: Edinburgh, UK
Contact:

Re: Guide: Setting up source control for Battlefront mods

Post by Marth8880 »

Anakin wrote:Nice tutorial. But why svn and not git?
Because, as I explained, SVN is better at handling large binaries - at least in my experience.
Post Reply