Version control

Introduction

Version Control is a feature of the Creation Kit used by Bethesda developers to be to able to work on the same ESM file(s) simultaneously. Version Control is useful to modders because it can be used to merge the contents of ESP files into an ESM file. In the public version of the Creation Kit, Version Control is disabled by default. It can be enabled by following the instructions on this page.

Setting up locally

These instructions are aimed at those who want to use Version Control merely for merging data of ESP files into a ESM file.

Create the following folders, assuming that Skyrim is your Skyrim installation directory:

Skyrim\Data\CheckInBackup
Skyrim\Merging\Data
Skyrim\Merging\VersionBackup

Make the folders CheckInBackup and Merging shared in your local network (can be a fake network with just your PC in it). Copy Skyrim.esm (and possibly Update.esm) and one or more of your own ESM files to Skyrim\Merging\Data. These are the "network versions". Add the following to SkyrimEditor.ini (some entries may already exist, watch out for them):

[General]
bUseVersionControl=1
SNetwork Path=\\Maegfaer-PC\Merging\
SNewVersionBackupPath=\\Maegfaer-PC\Merging\VersionBackup\
SNetworkMasterPath=\\Maegfaer-PC\Merging\Data\
SLocalSavePath=Saves\
SLocalMasterPath=Data\
SLocalBackupPath=Data\CheckInBackup

Replace Maegfaer-PC with the name of your computer.

Now go to SkyrimEditorPrefs.ini (the other file) and add the to bottom:

[WhoCanMerge]
Maegfaer=1

Replace Maegfaer with your Windows User Account name.

Now start the CK, load Skyrim.esm (and possibly Update.esm) and your mod's ESM(s) by selecting file / Data files - or the yellow "folder" icon in the upper toolbar - and selecting them in the list of available mod files. While loading the files, the CK will probably show a warning dialog saying:

"DEFAULT: TESBitArrayFile::OpenAndMapBitArrayFile could not find '[modfile].fud'

This is expected - you can disable warnings.

When the mod files have finished loading, click on the "folder" icon again, select Skyrim.esm and click on the Details button. Answer with "Yes" when it asks to create an empty list. When the empty list shows, press 'Ctrl + Shift + B' and then press OK. Close and do the exact same for your mod's ESM(s). Now in your Skyrim\Merging\Data folders there are a number of files Version Control uses to merge ESP files into any of your ESM files.

If the "Empty List?" prompt doesn't come up, it's likely that there's something wrong with the username you have selected. There should be be a new file:

Skyrim\Merging\ConstructionSetNetwork.ini

containing (for example)

[Users]
1=Maegfaer
Maegfaer=1

Check that the username specified in here matches the one you specified in SkyrimEditorPrefs.ini. It may be different if your Windows user account has ever been renamed. The value created in ConstructionSetNetwork.ini is the one that the CK will use - copy it over to SkyrimEditorPrefs.ini.

Version Control is now ready to be used.

Using Version Control

Quick and Simple

Load the CK with your to-be-merged-into ESM file enabled and the ESP containing the data to be merged as Active. When the CK is done loading, click on the Version Control button to the far left of your upper toolbar. Check out all the forms you want to merge first, then select them again and press Check In. A new window pops up. Select the ESM you want to merge into. Choose No when it asks if you want to use a Check In Data file (CID) and there it goes, it merges the content of your ESP file into your chose ESM and resolves any formID conflicts.

Check Out/In

Remember that Version Control is a system made for a large group of developers building a world at the same time. Checking Out a formID means you "reserve" it, it gets "locked" in the Network master file (the ESM in Merging\Data) so that none modifies the same content at the same time, which would result in conflicts. Every dev always has a copy of the ESM on his local system (your regular Data folder). The reason why you need to Check Out (reserve it) before you Check In (merge it) is a part of this safeguard to prevent developers changing the same forms. These steps have little meaning if you only use Version Control on a local system. It is just how the system works.

CID files

When Checking In forms, the Creation Kit changes the formID's of those forms if necessary to prevent duplicated formID's in the ESM. It also changes the formID index to match the index of the ESM file. Any references in forms to other forms are adjusted to match the re-assigned formID's. On merging, all the re-assigned formID's get listed in a *.CID file in the SNewVersionBackupPath folder defined in the SkyrimEditor.ini. CID files can come in handy when merging Plugin A and B into an ESM, while plugin B depends on plugin A. Let's assume plugin A is merged into the ESM first. Plugin A's forms get new formID's, which breaks any references in plugin B to forms originating from plugin A. When merging Plugin B into the ESM, the CID file created in the merging process of plugin A should be selected when asked for. That way all broken form references in plugin B get changed to the re-assigned forms of the data originating from plugin A.

Trick to check out Skyrim.esm forms

Checking out forms that belong to Skyrim.esm doesn't work by default. This can be problematic if you have your own ESM file and want to merge ESP files into your ESM. You won't be able to check out any Skyrim.esm forms that the ESP file modifies, and are thus unable to merge such changes.

The fix for this is to temporarily turn off the 'Use Localized Strings' flag in the Skyrim.esm header. You can do this by opening Skyrim.esm in a hex editor, and changing the ninth byte from 81 to 01. First make a backup of Skyrim.esm just in case this goes wrong!

The start of the file looks like this by default:

54 45 53 34      2C 00 00 00     81 00 00 00

Change it to:

54 45 53 34      2C 00 00 00     01 00 00 00

Save the change and load Skyrim.esm in the CK. You'll get a good number of errors about strings and such, ignore them and press Yes to All. Now it's possible to Check Out forms that belong to Skyrim.esm. Merge any changed Skyrim.esm forms from your ESP into your own ESM, then exit the Creation Kit and revert the flag change.

Troubleshooting

Errors

The following errors do not appear to have any effect on the Creation Kit's functionality or on plugin data. It appears they can be safely ignored:

Unable to initialize PerForce, check your logs for more information.

MASTERFILE: File index # is invalid. Clamping to ##. Does a master file depend on more than one master?