Howto: Subversion externals basics

Here's a quick howto on using subversion externals to load other subversion repositories into various directories of your project. We use this at "work":http://www.rainstormconsulting.com to load in shared classes so that they're versioned in one location. We could possibly use something like "PEAR":http://pear.php.net to provide some of those but this method is nicer I think, and all in one spot. To setup an external for a directory in your repository, I typically start at the root project directory, say MyProject, and set it there. Externals are a "subversion property":http://svnbook.red-bean.com/nightly/en/svn.advanced.props.html which holds some text as to what to what paths pull from what URLs. The easiest method to edit externals I think is to use the svn propedit command. This will require you to have an editor set for EDITOR or SVN_EDITOR environment variable (and this applies to unix/osx type systems) before you can successfully use svn propedit. The actual property name is svn:externals and we can use the commands svn propset or propedit etc. to work with it, easiest is propedit so that's what I'll demonstrate.

$ cd MyProject $ export SVN_EDITOR=vim $ svn propedit svn:externals .

Now you can make changes to the externals of the current directory specified by '.', you can specify a path-url combination per line, then save and exit your editor to finish the change. The path part comes first, and is relative to where your setting the external. Example of the format:

classes/MyUtilities http://example.com/svn/MyUtilities/classes

Once your done adding externals, you can run svn update to actually pull down the external, you'll need to commit to actually push the external property change to the server so anybody else working on the project gets it too.

$ svn update $ svn commit -m 'Added external for classes/MyUtilities'

There, any changes made to the other repository or path will come down when you do svn update. You can also commit changes within that external's directory by just entering that and doing normal subversion commands.

Technorati Tags: howto, programming, subversion, svn, tutorial

Howto: Basic Subversion setup and usage

So you want to setup a Subversion(SVN) repository? Well I know the basics and hopefully I can give a nice to-the-point tutorial on how to get up and running with tracking your source code through SVN. Subversion can easily be used as a personal change tracking system on your local computer, or be used with a team to track changes from everybody and facilititate conflict resolution with similar changes. I also see it as a super undo in case you really manage to screw stuff up. Although proper version tracking requires you getting in the habbit of reguarly commiting changes. Read more for the tutorial (Decided to stop doing full posts on front page, getting LONG)

Update: If your using OS X, check out SvnX for a GUI for manging working copies, and doing some repository actions too.

Technorati Tags: howto, programming, subversion, svn, tutorial

To start, you need to install Subversion, I'm going to take the command line and OS X route for this tutorial, so if your on linux like a debian or ubuntu system, you could just do apt-get install subversion to get subversion installed. Also check Subversion Packages page for any binary installs of Subversion including one for OS X (I prefer the non-fink choice under Mac OS X binaries.) Now that it's installed, you can already dive in to using it, on OS X you may need to add /usr/local/bin to your path if it isnt' already (and if you chose the non-fink installer package.) Now that it's installed, we need to create a repository where we want to store the versioned data. This is done with the svnadmin command (along with any maintenance stuff, like repair if something ever was to go wrong, or migration.) For this tutorial, I'm going to create a folder in my home called svn where I can store multiple project repositories. You could also have one repository for all your projects, like at my job where there was no real reason to separate them (more headaches.)

$ mkdir ~/svn $ svnadmin create ~/svn/MyProject

No output wiill occur unless somethign goes wrong but nothing will go wrong unless you don't have permission on the folder specified or the path to it (~/svn) doesn't exist. Now that we have a repository created, we can import our project into this repository.

Often many projects that use Subversion setup a certain folder structure within to hold branches and to tag things. Tags are for marking a specific version with something like MyProject-1.0 and branches are for branching your project to go a different route than the main project 'trunk' as it's often called. This is entirely optional, but you want your folder structure setup exactly how you want it in the repository before you import. So I often use this scheme, so I'll have something that'll look like the image to the left. To import a project into a new repository, we use the svn command with the argument import, along with the project path and the repository path. I setup a directory in my home called Projects and in this is where MyProject resides, I'll navigate here and issue the command to import.

$ cd ~/Projects
$ svn import MyProject file:///Users/jerome/svn/MyProject -m 'Initial import of MyProject into the repository'

Note: It would've been easier to say ~/svn/MyProject but my unfamiliarity with shell makes it so I can't have shell automatically replace ~ with my home, since svn doesn't like file://~/svn/MyProject. Svn is more often used with http:// and svn:// type urls for remote repositories so this is nicer when we use those. You may have may have noticed the -m ' message' argument, which is specify the commit message, basically explaining what that change is doing. This is the way to specify the message on the command line, you can also edit it from within an editor if your on a linux machine, or have EDITOR or SVN_EDITOR environment variables set to something like vim or pico. In OS X with bash (or linux), you can do this instead of the above to type your message more naturally in an editor:

$ export SVN_EDITOR=pico
$ svn import MyProject file:///Users/jerome/svn/MyProject

Now pico will invoke and you can write your message, and save & exit to have it commit If all went well, you'll see a stream of "Adding MyProject/trunk" type messages saying it's addin ga file or folder to the repository. Once it's completed it'll say you've commited revision 1. We're not well on rour way of having a versioned project, but there's still one more important step before you can start coding and having it commited. When you work with a project that's versioned, usually regardless of what software your using like CVS or SVN, you have to check out a working copy before you can make changes and be able to commit them. You can't use the project you just imported because it won't know what's changed etc. So what we'll do now, is move that one aside and check out a new working copy so we can get started.

$ cd ~/Projects
$ mv MyProject MyProject-original
$ svn co file:///Users/jerome/svn/MyProject/trunk MyProject

Subversion will proceed to access the repository at file:///Users/jerome/svn/MyProject and check out a copy into MyProject from the repository directory called trunk. You can check out any sub-directory if you really wanted to, but we want to work with the main project which we put in trunk, so we're specifying that. This should result in our original project structure we setup but without the trunk,tags,branches folders, just the contents of trunk instead. Now is where you can start editing stuff within the newly checked out project, and start adding new files and commiting changes.

Now just run through the basics of working with your working copy. There's basicaly three important commands that you'll need to do what you will do the most. svn status, svn commit, svn add.

So if you modiefied a file, you can do run svn status to see what changed, and therefore what will be commited if you do 'svn commit' without any file arguments. So if we modified a couple files, we can run status and see that svn shows they are modified.

$ svn status M config.php M index.php

The M stands for modified as you might have guessed, there's also ? for a file/folder not versioned, A for a file that's goin gto be added, and others we can get into in another tutorial.

So now that we see we have changes, and we're happy enough to want to commit them, we can issue a commit command. Commit command can be told what files you want to commit, if your not ready to commit everything. But we're happy with all the changes listed by status so we'll just do

$ svn commit

And if EDITOR or SVN_EDITOR is set, pico or whatever editor specified invokes, and you can type in why your commiting. Or you can do...

$ svn commit -m 'Why i did this silly change'

So one more thing that you'll do as far as the basics, that's adding a new file you created, easily done with svn add.

$ svn add newfile.php

Note, this just tells subverison to add it when you commit, and also if you specify a folder when you do svn add, it'll lrecursively add everything within.

Those are the rough basics, and I'll hopefully go into more details in another tutorial. But your best reading the SVN Book which will have a lot of answered and how to do things, like setting up an Apache server to host yoru SVN repository.