Reorganised docs so easier to follow

2025-02-23 13:15:23 +00:00 · 2020-04-23 16:18:21 +01:00 · 2020-04-23 16:18:21 +01:00 · 0cd1b113e0
commit 0cd1b113e0
parent 452342cc59
1 changed files with 93 additions and 45 deletions
--- a/ReadMe.md
+++ b/ReadMe.md
@ -1,62 +1,62 @@
 # Steve's UE4 Scripts

-## Subversion Repo Creation Script
+## Summary

-This constructs the entirety of the starting repository from a Subversion URL
-(which should contain an empty repository, or at most empty trunk/branches/tags
-subfolders).
+These scripts are to help me set up a Subversion repository for UE4 without
+having to remember everything.

-Usage:
-```
-      ue4-svn-create.ps1 [-urn:]svnurl [[-path:]checkoutpath] [Options]
+We use a particular content workflow that SVN is set up to support:

-      -url         : Subversion URL; the ROOT path (should be empty)
-      -path        : Checkout path; if omitted append last part of URL to current dir
-      -help        : Print this help
-```
+1. All content creation files in `$REPO/MediaSrc` (subfolders by type)
+    > * These are typically in formats e.g. Maya that UE4 doesn't read directly, so outside `Content`
+    > * These files are *tracked* in SVN
+1. When exporting, output (`FBX`, `PNG`, `WAV` etc) goes 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)
+1. Binary content is marked as needing *locking* so UE4 will prompt you to check it out
+    > * This is to avoid accidental parallel changes to the (many) binary files UE4 uses
+    > * This is our overriding reason for using Subversion and not Git

-It does everything that the [setup script below](#subversion-repo-setup-script) does, 
-but also creates the trunk/branches/tags structure, and checks out trunk for you.
-It also commits all the changes so your repo is ready to go.
+Together the scripts below configure everything so I don't have to remember.

-Unreal doesn't let you create a new project inside a directory with contents,
-so create your new project elsewhere then copy it into this new trunk checkout.
-Unfortunately there's no way to avoid this because we need folders to exist
-to set SVN properties on them.
-
-Steps to create a new UE4 SVN project:
+## Steps to create a new SVN repo for a UE4 project

 1. Create new repo on your Subversion server, note the URL e.g. https://foo/bar
-2. Run `ue4-svn-create.ps1 [URL]` in the parent folder you want your project to live
-   * This will create a folder called "bar" by default due to URL suffix
-3. In UE4, create a new project somewhere else, then save & close
-4. **Move** the contents of the UE4 project into your "bar" folder
-5. Commit
-6. Open UE4 again and browse to the "bar" folder to open your project
+1. Run `ue4-svn-create.ps1 [URL]` in the parent folder you want your project to live
+1. This will result in a subfolder called "bar" by default due to URL suffix
+   > See [creation script usage](#subversion-repo-creation-script) to specify a different destination path
+1. After it's finished the script will have created the trunk/branches/tags folders for you,
+  and then checked out the trunk for you into "bar"
+1. You then need to copy the contents of your UE4 project into this folder
+    > (UE4 doesn't let you create projects in non-empty folders so if you haven't 
+     created a project yet, create it somewhere else then move the contents)

+## Updating an existing UE4 project

-## Subversion Repo Setup Script
+If you already have a UE4 project in Subversion, you can instead just run the
+[in-place setup script](#subversion-repo-setup-script) instead to configure it
+for the workflow discussed above. You'll just need to commit the changes
+after the script has completed.

-This is a second-level script to intialise the structure of an existing Subversion 
-trunk checkout for UE4. Run in the root of that trunk checkout - it will work
-for existing UE4 folders or blank repositories (you'll have to copy a UE4 project
-in later).
+## What these scripts do

-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
-```
+### Creation Script

-### What it does
+1. **Creates trunk / branches / tags folders**
+
+    If they're missing, the script creates them and commits to the root.
+
+1. **Checks out trunk**
+
+    This will become your working folder. 
+
+1. **Runs the setup script**
+
+   Performs all the steps from the [setup script](#-setup-script) below.
+   It then commits all these changes so the working copy is ready to use.
+
+### Setup Script

 1. **Ignore unnecessary folders**

@ -144,3 +144,51 @@ Usage:



+## Script Reference
+
+### Repo Creation Script
+
+This constructs the entirety of the starting repository from a Subversion URL
+(which should contain an empty repository, or at most empty trunk/branches/tags
+subfolders).
+
+Usage:
+```
+      ue4-svn-create.ps1 [-urn:]svnurl [[-path:]checkoutpath] [Options]
+     
+      -url         : Subversion URL; the ROOT path (should be empty)
+      -path        : Checkout path; if omitted append last part of URL to current dir
+      -help        : Print this help
+```
+
+It calls the [setup script below](#subversion-repo-setup-script), 
+plus creating the trunk/branches/tags structure, and checking out trunk for you.
+It also commits all the changes so your repo is ready to go.
+
+Unreal doesn't let you create a new project inside a directory with contents,
+so create your new project elsewhere then copy it into this new trunk checkout.
+Unfortunately there's no way to avoid this because we need folders to exist
+to set SVN properties on them.
+
+### Repo Setup Script
+
+This is a second-level script to intialise the structure of an existing Subversion 
+trunk checkout for UE4. Run in the root of that trunk checkout - it will work
+for existing UE4 folders or blank repositories.
+
+None of the changes are committed so you can review them.
+
+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
+```
+