diff --git a/ReadMe.md b/ReadMe.md new file mode 100644 index 0000000..69d0b1e --- /dev/null +++ b/ReadMe.md @@ -0,0 +1,111 @@ +# Steve's UE4 Scripts + +## Subversion Repo Setup Script + +This initialises the structure of a Subversion repository for UE4 +usage. Run in the root of a new Subversion repository, whether you've created +the UE4 project in there yet or not. + +Usage: +``` + ue4-svn-setup.ps1 [[-src:]sourcefolder] [Options] + + -src : Source folder (current folder if omitted) + : (should be root of trunk in new repo) + -skipstructurecheck + : Skip the check that makes sure you're in trunk + -overwriteprops + : Replace all properties instead of merging + : Will overwrite svn:ignore, svn:global-ignores, svn:auto-props + -dryrun : Don't perform any actual actions, just report on what you would do + -help : Print this help +``` + +### What it does + +1. **Ignore unnecessary folders** + + It ignores folders in the root we don't need in Subversion: + + * .vs + * Binaries + * Build + * DerivedDataCache + * Intermediate + * Saved + + It sets the `svn:ignore` property in the root folder to do this. It will merge + with the contents of any existing property by default. `svn:ignore` is + not set recursively and does not get inherited (despite what TortoiseSVN + gives the impression of). + +1. **Sets binary files to needs-lock** + + By setting the `svn:auto-props` value for common binary types tracked in the + repo such as .uasset and .umap, it enforces locking on those files, + triggering UE4 to give you check out prompts when you edit those files. + + This property is set on the root folder and is inherited throughout the tree. + +1. **Creates folder structure** + + Subversion, and particularly TortoiseSVN has a "quirk" whereby inherited + properties are not respected for files inside a folder that isn't added to + SVN yet. This means that if you rely on `svn:global-ignores` being inherited + from a parent, a file inside a new folder that *should* be ignored is still + shown in the Add/Commit TSVN dialog, until its parent folder is added, at + which point it is hidden. + + I maintain this is *extremely* dumb behaviour because you can easily add + files that should be ignored by accident, unless you manually add the folder + first. However a big TSVN thread froma few years back has defended this + bizarre approach as "by design". So to mitigate this, I pre-create the + majority of our preferred folder structure ahead of time. + + Our preferred **workflow** is: + + 1. All content creation tool files in `$REPO/MediaSrc` (subfolders by type) + * These are typically in formats UE4 doesn't read directly, so outside `Content` + * These files are tracked in SVN + 1. When exporting, place output (`FBX`, `PNG`, `WAV` etc) in `$REPO/Content` (and subfolders) + * These files are *ignored* in SVN because they are derived data + * UE4 imports them to a `.uasset` which contains all their contents anyway + 1. All `.uasset` post-imported content in `$REPO/Content` is tracked in SVN (binary) + + So the tool pre-creates `MediaSrc`, `Content` and subfolders (if they don't already + exist), and add them to Subversion ahead of time to head off as many quirks + as possible. + +1. **Ignore derived export data in Content folder** + + As discussed in the workflow section above, exported files like `PNG` and `FBX` + are not committed because they're duplicated data (source is in Maya/Blender/Photoshop files in `MediaSrc`, game-ready data is in `.uasset` files in `Content`). So we want + to ignore them underneath `Content`. + + The `svn:ignore` property isn't helpful because it isn't inherited by subfolders, + and if you set it recursively it only applies to folders that already exist. + Although we've tried to help by creating most of the structure up-front, we + don't want to preclude creating new folders, and don't want everyone who + does so to have to remember to set the `svn:ignore` up. + + So instead we use `svn:global-ignores`, a newer property that is inherited + by children (although as noted above it behaves a little oddly before you add + folders to SVN, but at least you don't have to set the property again). Any + `PNG`, `FBX` files you export into `Content` for import will be ignored, and + you can just commit the `.uasset` files, and the original sources in `MediaSrc`. + The export files can be considered temporary. + + + > We set `svn:global-ignores` for all the common intermediate formats *only* + > on the `Content` folder. This is so that if, for some reason, you don't have + > a typical content creator file for an asset and for some reason you want to + > store the `PNG` or `FBX` for it manually (instead of just the `.uasset`, which is all + > the game needs), you can put those files in `MediaSrc` if you want, and copy + > them to `Content` for importing as a substitute for the normal export workflow. + > + > In practice I don't think you need to do this, because you can export `.uasset` + > files anyway. Probably better to just put orphaned files like this directly in + > `Content` and only commit the post-import `.uasset`. But the option is there. + + + diff --git a/ue4-svn-setup.ps1 b/ue4-svn-setup.ps1 index 47f69dd..a6d3556 100644 --- a/ue4-svn-setup.ps1 +++ b/ue4-svn-setup.ps1 @@ -11,7 +11,7 @@ param ( function Print-Usage { Write-Output "Steve's UE4 Subversion Repo Setup Tool" Write-Output "Usage:" - Write-Output " ue4-svn-setup.ps1 [-src:sourcefolder] [-skipstructurecheck]" + Write-Output " ue4-svn-setup.ps1 [[-src:]sourcefolder] [Options]" Write-Output " " Write-Output " -src : Source folder (current folder if omitted)" Write-Output " : (should be root of trunk in new repo)" @@ -19,7 +19,7 @@ function Print-Usage { Write-Output " : Skip the check that makes sure you're in trunk" Write-Output " -overwriteprops" Write-Output " : Replace all properties instead of merging" - Write-Output " : Will overwrite svn:ignore, svn:global-ignores" + Write-Output " : Will overwrite svn:ignore, svn:global-ignores, svn:auto-props" Write-Output " -dryrun : Don't perform any actual actions, just report on what you would do" Write-Output " -help : Print this help" }