User Tools

Site Tools


opu:repository

Outpost Universe Repository

The Outpost Universe maintains source code and other development documents in an online hosted Subversion (SVN) repository. Online navigation of the repository is through VisualSVN Server. There are no restrictions on who can pull a copy of the repository. To write files into the repository, contact an Outpost Universe Admin about gaining write access.

Before posting content to the repository, read through the guidelines below. Remember all data in the Outpost Universe repository is meant for public access.

Outpost Universe Repository: https://svn.outpostuniverse.org:8443/!/#.

Accessing the Repository

A user will typically download sections or the full repository to their computer. Then, they can periodically update their local copy of the repository with changes made to the primary online repository. When they are ready to contribute public changes to the repository, a user should commit them to the primary online repository for others to download.

To manage pushing and pulling information from the repository, typically an application that understands subversion is used. There are many choices, but a lot of contributors on Outpost Universe use Tortoise SVN, a free Windows shell extension. Once Tortoise SVN is installed, you can right-click on folders on your computer and select the appropriate action from the context menu.

If you take turns editing files, the information below is most everything you'll need to know. If two people work concurrently on the same file, then there are a few more things you'll need to know regarding Conflicts and Merging. You can check the help file or the Subversion book (see below) for details on how to handle this.


Typical Repository Usage

Repository Browser: Once Tortoise SVN is installed, you can view the repository by right-clicking pretty much anywhere in Explorer (not Internet Explorer, just Windows Explorer).

  1. Click TortoiseSVN → Repo-browser. Enter the URL (https://svn.outpostuniverse.org:8443/!/#) and click ok.

Export Command

Export lets you get a copy of a subtree from the repository. This is most suitable if you don't intend to commit any changes. (You're just leaching the file). Choose TortoiseSVN → Export…, and then enter the Repository URL of the subtree you'd like to retrieve. You can click on the “…” to open the Repository Browser to select the right folder. You probably want to do this into a new empty folder. It defaults to storing the local copy in whatever folder you've right-clicked on, or had selected when you opened the context menu.

Checkout Command

Checkout lets you get a “working copy” of a subtree from the repository. This is what you need to do if you intend to submit changes. (You're also free to use this option if you're only leaching, as it in no way locks out anyone from getting or changing files on the server). Checkout creates an extra .svn folder in each of the checked out folders. This extra .svn folder contains a cached copy of each of the files that were checked out. This lets the client do a diff (compare) of the last checked out version of the file with the current working copy, so when changes are submitted to the server, only the difference needs to be sent rather than the whole file. This can save a lot of time for commits of large files. It also lets you revert any changes you make without needing to contact the server, which is particularly convenient if you're no longer connected to the internet. Checkout works pretty much the same as the Export option, except you just select the “SVN Checkout…”.

Update Command

Update lets you download changes to a working copy. You must have already run Checkout to see this option. It is only available on checked out folders. If you check out a copy, and then someone submits a change to the server, you can run Update to download a copy of the change. The change is sent as a diff from your last checked out version, so it should run fairly fast for small updates, even on large files. If you changed the same local file that was updated on the server, then you will be informed of this. It won't just overwrite your local changes.

Commit Command

Commit (aka checkin) lets you submit changes from your working copy to the server. You must have already run Checkout to see this option. It is only available on checked out folders. Note: You need to have write access to do this. The server I set up requires a login name and password before you can run a commit.

Diff Command

To see a list of changes between revisions of a checked out copy, by choosing TortoiseSVN → Revision graph, and using Ctrl+click to select the two revisions you want to compare, and then right-click to see a menu of possible compare options.


Repository Best Practices

Understanding how a repository works and using the right commands for manipulating the repository will keep it smaller and allow better tracking of file changes.

Always Log a Summary When Submitting Commits

You should enter a log message with your commit to summarize why the change is being made. This can be really simple, but generally shouldn't be blank. Take a look at the log for examples of messages. This makes searching for a specific change easier. Examples might be “Added new project X”, or “Fixed bug X”, or “Added feature X”.

Commit Source Files, Not Compiler Output

You should (usually) only commit source files, not compiler outputs. The compiler outputs are perhaps more useful in a release pack (zip/rar) rather than in the repository, or in cases where there is no source code and work is done directly on the binary code, such as patches to Outpost2.exe. You should not generally commit compiled DLL files for level projects, and you should definately not commit intermediate files, such as .obj files. I generally add an ignore for any Debug/, Release/, or Release-MinSize/ folder to ensure they don't get accidentally committed. Files which should be committed are source files (.cpp, .h), and project/workspace (solution) files (.dsw, .dsp for MSVC6, .sln, .vcproj for Visual Studio 2008). If you make changes to the project file using VS2008, then by all means, commit the VS2008 project files to the repository. You should probably not commit other files that are generated automatically by your development environment. Also, be aware that the other files may contain personal information, such as your login account name.

Submit Changes, Do Not Constantly Delete and Re-Add File

You should not constantly add and remove files to update them. If you make changes to a file, you may notice Tortoise SVN has a little red exclaimation icon overlaid on top of the file's icon. This is to let you know that your local working copy has changed from the last sync with the repository. The proper way to push that change to the repository, is with an SVN commit (or perhaps an SVN revert). Doing an SVN delete, following by an SVN add is a lot more expensive in terms of storage costs in the repository, and it also breaks history (the log) and requires more bandwidth for the new addition. The strength of SVN is that is stores changes to files between version, rathern than complete copies of each version.

Create Branches with SVN Copy

If you are creating a new branch of an existing project in the repository, or perhaps starting a new one using an old project as a template, try using SVN copy. Again, this is cheaper in terms of repository storage, and you can potentially trace history across the copy to see where the project comes from. For instance, when creating a new level, you can potentially start with an SVN copy of the blank template project. To do an SVN copy from Windows Explorer, right-click drag the file or folder to it's new destination. When you release the right mouse button, a menu will pop up asking you what you want to do. You can choose SVN copy, SVN move, regular copy, and regular move.

Moving or Renaming Tracked Files

Use SVN move to move or rename an existing file. Again, this is cheaper to store, and doesn't break history. SVN move uses the same right-click drag method as SVN copy.


Resources

This information was pulled from forum posts by Hooman.


- Go Back to Outpost 2 Mapmaking
- Go Back to Wiki Home Page

opu/repository.txt · Last modified: 2016/10/12 16:32 (external edit)