Sphere Community Game/Subversion

From Spheriki

This page holds info on how to use Subversion with the Sphere Community Game if you're working on it.

Contents 1 The initial checkout 1.1 With TortoiseSVN 1.2 With svn 2 The work cycle 2.1 Update your working copy 2.1.1 With TortoiseSVN 2.1.2 With svn 2.2 Make your changes 2.2.1 The idea 2.2.2 Adding files and directories 2.2.2.1 With TortoiseSVN 2.2.2.2 With svn 2.2.3 Copying, moving and deleting files and directories 2.2.3.1 With TortoiseSVN 2.2.3.2 With svn 2.2.4 Look at your changes 2.2.4.1 File/directory status 2.2.4.1.1 With TortoiseSVN 2.2.4.1.2 With svn 2.2.4.2 Exact changes in files 2.2.4.2.1 With TortoiseSVN 2.2.4.2.2 With svn 2.2.4.3 Undoing your changes 2.2.4.3.1 With TortoiseSVN 2.2.4.3.2 With svn 2.2.5 Merge others' changes 2.2.5.1 Finding what conflicts need resolving 2.2.5.2 Extra files?! 2.2.5.3 Fixing conflicts 2.2.5.3.1 By hand 2.2.5.3.2 Copying a special file 2.2.5.3.3 Throwing away your local changes 2.2.5.4 Resolving conflicts 2.2.5.4.1 With TortoiseSVN 2.2.5.4.2 With svn 2.2.6 Commit your changes 2.2.6.1 With TortoiseSVN 2.2.6.2 With svn 2.3 Those funny letters 2.3.1 What about svn status? 3 Summary 3.1 Starting off 3.2 Beginning a session of work 3.3 File/directory operations 3.4 Looking over what you've done 3.5 Changing your mind 3.6 Conflicts and how to solve them 3.7 Wrapping things up 4 Conclusion

The initial checkout

Okay, you're itching to get started. You've installed your SVN client. You want the latest development version of the game.

What you want to do is known as a checkout. It grabs a full, complete copy of the project and downloads it to your computer, ready for you to work on.

With TortoiseSVN

• Create a new directory somewhere with any useful name (like sphere_cg).
• Right-click on the new directory and select 'SVN Checkout'.
• Enter svn://spheredev.org/scg as the Repository URL and click OK.
• The respository should now be downloading to your computer, to the assigned directory.

With svn

Open up a terminal, and type the following:

svn checkout svn://spheredev.org/scg/trunk sphere_cg

After a string of file download messages, a new directory called sphere_cg/ will show up. This is a copy of the latest version of the project.

You can shorten the command to this:

svn co svn://spheredev.org/scg/trunk sphere_cg

Here, checkout has been shortened to co. Many commands with svn can be shortened this way.

The work cycle

Here it is, in short:

1. Update your working copy.
   • svn update
2. Make your changes.
   • svn add
   • svn delete
   • svn copy
   • svn move
3. Look at your changes.
   • svn status
   • svn diff
   • svn revert
4. Merge others' changes if needed.
   • svn merge
   • svn resolve
5. Commit your changes.
   • svn commit

You don't have to remember all of these commands. We'll only cover the bare essentials needed to do basic work.

Update your working copy

Before you sit down and start making changes, you need to make sure you have the latest version of the project. After all, while you were asleep, or even just away at lunch, somebody could have made changes to the project.

What you want to do is update your local copy of the project.

With TortoiseSVN

Whenever you want to update your copy of the game with TortoiseSVN, right-click on the checked out directory and select 'Update'. The new files are added, edited files are updated etcetera.

With svn

Open up that terminal, and navigate into the directory named sphere_cg/, so you're inside it. Type this:

svn update

More file status lines will appear, like the ones you saw with your first checkout. If things went well, no error messages should have popped up. If they do, take a peek at the section named "Those funny letters" to figure out what's up.

Make your changes

If the update went well, the next step is to make your changes.

The first kind is just opening up one of the project files, making your changes, and saving them. If that's what you're doing, you don't even need to read this section for now.

If you're making new files and directories, or changing and deleting them, this section is for you.

The idea

Instead of using your regular file management operations, you use Subversion's operations. They are:

• add: add files/directories
• delete: delete files/directories
• copy: copy files/directories
• move: move files/directories

When you use these types of commands, the changes are local until you upload them back to the server at the end of your session. Until then, you can happily reverse these changes whenever you feel the need.

Adding files and directories

You're inside your project directory, and want to add a new file.

First, create the file normally using any editor. If it's a directory, just create the directory as you would normally.

Now you have to tell Subversion that you want to put your changes up in the repository.

With TortoiseSVN

• Right-click the checked-out directory (or any of its subdirectories if you want to checkout only that one).
• Pick what changes to make to the repository (it lists any files that are different compared to the repository).
• Click OK and your changes will be applied to the repository.

With svn

If your file or directory is named "foo", just type something like this:

svn add foo

That's it!

Copying, moving and deleting files and directories

With other operations, it's even simpler. Don't use your regular file system operations, just use these SVN commands.

With TortoiseSVN

If you copy, move or delete files, these changes will be listed in the commit menu. Change your files as necessary, and commit the changes in the commit window.

NOTE: Moved files will have two commands to the SVN repository, which are 'delete file with original name' and 'add file with new name'.

With svn

To copy the contents of a file "foo" to a new, non-existent file named "bar":

svn copy foo bar

To move file "foo" to the new location "bar":

svn move foo bar

And finally, to delete the file "foo":

svn delete foo

It's that easy! Plus, these instructions can be used with directories as well, so if you feel like copying, moving or deleting directories, you can apply the same knowledge from here onto them. Awesome!

Look at your changes

If you only made small changes, you don't need to read this section. But if you made lots of changes, it's a good idea to take a look at what you've done before you wrap things up.

File/directory status

This one's pretty useful, you'll probably end up using it a lot. With it, you can see what you've changed, what you need to fix, and so on.

With TortoiseSVN

When you open a directory, you can immediately see which files are changed, which one are not changed, and which files aren't in the repository yet.

• Changed files will have a red exclamation mark over their icon.
• Up-to-date files will have a green icon with a V in it.
• Files that are not in the repository do not have any extra icon over them at all.

Note that you can't see these icons if you use custom file browsers instead of Windows Explorer in Windows.

With svn

Type this:

svn status

Four columns of letters will appear, and next to them will be file and directory names. You can see this and what they mean in the SVN guide. There's too many symbols to describe, or even remember, so just look them up when you need to.

The above only looks at local changes. What happens if somebody did work while you were working, and saved it on the server before you could? Here's how to find out:

svn status --show-updates

Asterisks may appear next to some files and folders. That means they were changed on the server, but not on your local box. If you modified any of the files/directories and an asterisk appears next to them, you'll probably have to resolve using svn update. But more on that later.

For now, just relax, safe in the knowledge that you're aware of what's going on with the project on the server, and not being kept in the dark.

Exact changes in files

Okay, you have the general overview, but what about exactly which lines of a text file you added/altered/removed? Well, Subversion makes this easy as well.

With TortoiseSVN

Right click the directory that contains your local copy of the repository. From the context menu select TortoiseSVN->Check for modifications. This will bring up a box containing a list of all the files that have been modified since you last committed. Double clicking on one of these files will open TortoiseMerge. This lists all the changes that have been made in the current file since the last commit.

With svn

Type this:

svn diff

Or just for a single file named "foo":

svn diff foo

Lines that you have removed will appear with a - before them. Lines added will have a + before them. Easy!

It's easy to make patch files. Unix users know enough about patch files and how to apply them, or can easily learn. Here's how to make them:

svn diff > mypatchfile.patch

Now your patch is stored in "mypatchfile.patch". You can send this patch to other team members, and they can either apply it, or look inside it and make the changes manually.

Undoing your changes

So you made a mistake with a file. Or you just changed your mind. That's okay, svn can quickly and easily undo your local work. We use svn revert for this.

With TortoiseSVN

(ed: Free candy for anybody who fills in this section!)

With svn

To undo your changes to a file named "foo", between now and the last svn update:

svn revert foo

That's it! The file "foo" will now be just like it was before you starting messing around with it.

Merge others' changes

If things went smoothly, you can safely skip over this chapter. If not, read on!

Finding what conflicts need resolving

Just use svn update like at the beginning of your work session. If you see something like:

C   foo

This means that Subversion has found a conflict with the server's version of "foo", and your local file "foo". We can fix this, but for now we know what's up.

Extra files?!

Subversion makes extra helper files to help you fix that conflict with the file "foo":

• foo.mine: Just what you had for "foo" on your local box before the latest svn update.
• foo.r<old_revision_number>: The file "foo" as it was, before you made your local changes.
• foo.r<new_revision_number>: The file "foo" like it is on the server now.

Subversion will not allow you to commit while these files exist.

But why? Well here's the special bit: Subversion puts special conflict markers inside the file "foo". You'll know them when you see them, but they'll be described later anyway.

Fixing conflicts

So the file "foo" is in a state of conflict, but the question remains: what do I do? Well, you've got three choices:

• Fire up your text editor with "foo", and fix things by hand, using the conflict markers. Described above.
• Copy one of those special files over "foo."
• Use svn revert foo to throw away your local changes.

By hand

First off, if you're going down this road, now is a good time to get in contact with the person who last committed (or the team in general), either through IM, email, the forums or whatever, and talk to them about what should be done. When you come to an agreement, make your changes here and keep on truckin'!

Anyway, conflict markers look a bit like this (inside "foo"):

And when he gets to heaven
To Saint Peter he will tell
<<<<<<< .mine
"Reporting here for duty sir
I've served my time in hell."
=======
"Church is damn boring.
Why'd you have to establish it?"
>>>>>>> .r21

Here's what you have that differs from what's on the server:

<<<<<<< .mine
"Reporting here for duty sir
I've served my time in hell."
=======

Here's what's on the server; it's revision number 21 here:

=======
"Church is damn boring.
Why'd you have to establish it?"
>>>>>>> .r21

All you have to do is pick the section you want kept, remove the one you don't, and get rid of those funny lines with the symbols on them.

Keeping your changes, you'd tweak the file to look like this:

And when he gets to heaven
To Saint Peter he will tell
"Reporting here for duty sir
I've served my time in hell."

While if you wanted the server's changes:

And when he gets to heaven
To Saint Peter he will tell
"Church is damn boring.
Why'd you have to establish it?"

Copying a special file

Instead of making the changes by hand, you can copy one of those special files over "foo".

Remember these?

• foo.mine
• foo.r<old_revision_number>
• foo.r<new_revision_number>

Well, you can just pick one of these instead of hand trawling through the file "foo", if that's how you want to do things.

Throwing away your local changes

Just type:

svn revert foo

And foo will just as it was before you started working on it.

Resolving conflicts

Now you have to tell Subversion that you've fixed things, using svn resolved. This isn't needed if you used svn revert to solve things.

With TortoiseSVN

(ed: If you know them instructions, best you be puttin' 'em here.)

With svn

Type this:

svn resolved foo

Now Subversion will know things are okay again. As a special favour, Subversion removes those three special files, since you don't really need them anymore. That's it!

Commit your changes

This one is important!!! Okay, now that i have your attention, here's how to make all your changes visible to everybody else, by saving it onto the server. This is known as commiting your work, and it's easy to do:

With TortoiseSVN

Right-click anywhere in your Explorer window while the contents of the project are visible. Choose Commit.

A prompt will appear for a log message. Write a brief sentence in the dialog about what you changed in your session, and click Commit.

That's all!

If you change your mind and don't want to commit, just click Cancel at the prompt.

With svn

In the directory of the project, type this:

svn commit

Or the shorter form:

svn ci

An editor will pop up for you to enter a log message. Write a sentence or two about what changes you made in your session. Save it and close the editor, and Subversion will commit your work.

If you change your mind and don't want to commit, just quit the editor without typing anything. If you already saved, just clear the text and save again. Subversion will bring up a prompt asking if you want to abort or go ahead: choose Abort.

To add a log message without jumping into the editor, type something like:

svn commit --message "Filled the file foo with some _real_ lines."

To add a log message that you've already written into a small text file, type:

svn commit --file my_log_message_file

Make sure that the file "my_log_message_file" is only a few lines at most!

Those funny letters

Since most of this was shamelessly adapted from the SVN guide anyway, here's the link to the table of symbols when updating or committing.

It's reproduced here for your convenience:

U   foo

File "foo" was updated (changes received from the server.)

A   foo

File "foo" was added to your local working copy of the project.

D   foo

File "foo" was deleted from your local working copy.

R   foo

File "foo" in your local working copy was replaced by a new file named "foo" on the server.

G   foo

File "foo" received new changes from the server, but your local copy of "foo" has been changed. Subversion merged the changes, all is well. Subversion is cool like that.

C   foo

File "foo" is in conflict! That is, your local copy of "foo" has been changed, but it overlaps with changes to "foo" on the server. You have to fix this by resolving the conflict somehow.

What about svn status?

In lieu with the rest of this page, here's the link to the table of symbols when using svn status.

It's also here:

A file_or_dir

"file_or_dir" is scheduled for addition when you next run svn commit.

C foo

The file named "foo" is in a state of conflict. Changes you made to your local copy overlap with those of the server. You need to fix this before svn commit will work.

D file_or_dir

"file_or_dir" is scheduled for deletion from the repository.

M foo

The contents of "foo" have been modified in your local copy.

X dir

I have no idea what this means, but the guide says: The directory dir is unversioned, but is related to a Subversion externals definition. To find out more about externals definitions, see the section called "Externals Definitions".

? file_or_dir

Subversion isn't tracking or doing anything with "file_or_dir". It's not on the server, Subversion won't touch it unless you use svn add or whatever. You can silence this with the --quiet (or -q) switch to svn status, or setting the svn:ignore property on the parent directory. (ed: If you know how to set this "svn:ignore" property, tell us!)

! file_or_dir

"file_or_dir" is being tracked by Subversion, but it's missing/incomplete. This can happen if you delete "file_or_dir" without using svn delete. Use svn update to grab the file from the repository again, or svn revert file_or_dir to nab it from your local cache.

~ file_or_dir

"file_or_dir" is being tracked by Subversion, but it somehow changed from a file into a directory, or vice versa, without Subversion's knowledge. If "file_or_dir" was a file before, but was deleted and replaced with a new file named "file_or_dir" without the svn add/delete commands, this will show up.

I file_or_dir

"file_or_dir" is actively being ignored by Subversion. This only shows up if you pass --no-ignore to svn status.

Summary

Starting off

Download the project for the first time if you don't have it already:

svn checkout svn://spheredev.org/scg/trunk sphere_cg

Beginning a session of work

For each session of work, update your working copy:

svn update

Changes won't be saved on the server/repository until you run svn commit at the end of your session.

File/directory operations

If a file/directory named "foo" needs to be added, first make it normally, then:

svn add foo

If "foo" needs to be copied/moved to "bar", or deleted, then:

svn copy foo bar
svn move foo bar
svn delete foo

Feel free to change the contents of files as you would normally.

Looking over what you've done

To find out an overview of what you've done:

svn status

Or what you've done compared to the latest server version:

svn status --show-updates

If you want to see exactly which lines of files were changed:

svn diff

Or for a single file named "foo":

svn diff foo

Changing your mind

If you made changes in "foo", but change your mind about going through with them, you can revert them using:

svn revert foo

Conflicts and how to solve them

Subversion can find and detect conflicts when you run svn update. The new files created for a file "foo" in conflict are named:

• foo: Original file, plus conflict markers.
• foo.mine: Your local working copy of "foo."
• foo.r<old_revision_number>: "foo" as it was when you ran svn update before starting your work.
• foo.r<new_revision_number>: "foo" as it is now when ran svn update just now.

Contact the person on the team with the last commit, or the team itself. Once you've come to an agreement, resolve the conflict in one of three ways:

1. Go through "foo" and make the changes by hand, using the conflict markers.
2. Copy one of those new special files over "foo" that svn update just made for you.
3. Run svn revert foo.

If you chose methods 1 or 2 (3 doesn't need it), you need to tell Subversion that you solved the conflict:

svn resolved foo

Wrapping things up

Finally, you want to commit your changes so that they're saved in the repository:

svn commit

That's all folks!

Conclusion

If you read this far, congratulations! You're either really dedicated, or have too much time on your hands.

If you want, you can read the official guide, which I largely ripped off anyway.

Cheers! --Tunginobi 12:49, 23 February 2007 (GMT)