The power of SVN externals in your project
A post about how leveraging externals can be a powerful tool used across multiple projects.
This is quite an in depth post so stick with it but it covers how to use externals in as much depth as possible.
Over the past few months I have been coming up against an increasing need to share settings, source files, game files etc. across more than one project. By this I mean having a substance settings folder with hundreds of filters or an entire repository that needs to be shared across multiple project trunks.
By using SVN externals we can easily do this. SVN allows us to hook in a directory from a separate repository.
A weapons artist working out of their own repo still needs access to the tools but we also need access to their exported weapons for use in our project repositories.
For this we can use SVN externals to hook in our tools for them to use and also hook in their exported weapons for us to use in various projects
The diagram below illustrates the philosophy behind using externals.
By housing our repositories separately we can share them between projects
Each discipline can work separately in their own repository and share their work across multiple projects
We are going to explore two ways of using externals for our project, one will use a HEAD revision and the other will use a PEGGED revision.
Our HEAD revision will be used to hook in an entire repository into our trunk and our PEGGED revision will be used for hooking in tools and allowing us to control which version of the tools the end user will have access to.
REMEMBER: Do not commit to a PEGGED external, this can cause instability in your project and PEGGED externals are supposed to be downstream only, so be careful! Commiting to an external set to HEAD is totally fine.
We are going to run through how to set up an external and then we will dive into the differences between HEAD and PEGGED
Go to any folder in your project trunk, this could be the root or any folder inside.
Right click -> Tortoise SVN -> Properties:
You will be greeted by 3 individual dialogs as you set up an external.
The SVN properties window will pop up for you, choose New... -> Externals
You will be greeted by the create new externals window:
Edit external dialog explained:
Local path: This is the local folder that your external will live in, this is a requirement for setting an external. When you reference an external repo, SVN will take all of the data from inside the folder you have specified i.e. all files, directories and sub-directories.
URL: The SVN URL is the repository URL that you wish to reference. e.g. https://myprojecturl.com/svn/maya-tools
When you set the HEAD revision for your external this simply updates to the latest revision when the user updates the folder or trunk.
When the weapons artist submits some new weapons, the end user updates and sees them immediately. Setting the external to HEAD requires little to no maintenance as the external will just update like any other normal SVN folder.
Choosing this option allows us to version our external, to do this we must set a PEG.
What exactly does PEG mean?
The PEG is simply the revision number we want our external to update to for the end user. Pegging our external allows us to control which version of the external we want people to use. Using a PEGGED external will require some maintenance.
revision 30 - Added new tool
revision 29 - Bug fixes
revision 28 - Bug fixes
revision 27 - Added error checking functions
revision 26 - New icons added
The above example shows the last 5 revisions in our repository.
By setting our external to work on REVISION instead of HEAD we directly control which revision number the end user will be able to use.
If revision 30 has work blocking bugs, we can roll back the PEG to revision 29 allowing the user to work once more.
Or if a tech artist has recently submitted some new changes they can choose not to update the PEG until it has been tested.
Maintaining your PEGGED external:
Setting an external to be PEGGED to a revision requires you to update or roll back the peg.
To do this go to the folder you have set the peg to:
Right Click -> Properties -> Select your desired external -> Edit -> Select desired external -> Edit -> set peg number.
Or alternatively when you get to the edit externals window you can:
Right Click -> Fetch HEAD revision and adjust to it.
When you have done this be sure to commit the change!
I hope you have found this tutorial on how to leverage externals in your project useful. Remember to tread carefully with externals, as useful as they are when used incorrectly can cause project instability.