If you’re already quite familiar with SVN, you might want to at some point want to use the command line interface (CLI) to get its full potential. This article will explain some of the possibilities and how it’s done.

Table of contents
Setting it up
How commands are structured
General commands (checkout, update, checkin, add)
Property commands (proplist, propget, propset, propdel)
File commands (ls, cat, copy, rename, delete)
Info commands (info, status, help, log)
Advanced commands (diff, revert)
Using SVN remotely

Setting it up #
Before we can start, we need to install the subversion binaries. Go to subversion.tigris.org, or more precisely the downloads page. Download the latest zip package. At the time of writing this article that is “svn-win32-1.4.6.zip“. Extract it somewhere on your HD, I put it into c:\tools\svn, but that’s up to you. You can remove the “share” folder, I’ve had problems with svn not working when in “german mode”, so I just use it English. Done, SVN is installed . Now let’s see if it’s working. Click Win+R and enter “cmd” to open a new command line window. cd, which stands for “change dir” is used to change into a different folder. So let’s change into the svn folder by entering: cd c:\tools\svn\bin (note the \bin). if the path contains spaces, you have to set the whole path into quotes. Now type “svn” (the .exe can be omitted). Now you should get “Type 'svn help' for usage.”. Congratulations, you have svn working!

Now we have a little problem, if we are in a directory and want to perform svn actions, we can’t just type “svn”, we have to type “c:\tools\svn\bin\svn”. To solve this, windows has this thing called the “PATH”, which is a so-called “environment variable”. It’s a list of paths that are searched automatically when entering a command in the command line. So, let’s add our SVN folder to that. Right click onto “My computer” and choose “System properties”. In the “Advanced” tab there should be a button called “environment variables”. Now you get a window with “User variables” at the top and “System variables” at the bottom. In the bottom list, find “PATH” or “Path” and click “Edit”. At the very end, add “;c:\tools\svn\bin\” (note the ; at the beginning, it’s used as a separator). A reboot is required to make the variable work, so I suggest you do that before reading on.

To check if it worked, open a command line window and type “svn”. If you get the “Type ‘svn help’ (…)” message, it worked. 

Now, how do you work with CLI SVN? You have to make sure to cd into the correct directory before doing anything. So you can try this:

Code: Select all

cd c:\
mkdir work
cd work

Now we have a working directory to mess with.

How commands are structured #
To begin with, one page you may want to bookmark is the official documentation, so you can look up all of the commands later on. It’s something like the PHP manual, just for SVN.

All SVN commands are structured like this:

Code: Select all

svn <subcommand> <options> <arguments>

The subcommand is something like commit, checkout, update. It’s called a subcommand because the main command is “svn”.

The options are optional and they are used to specify a revision for the action, or username/password. They are in this format: --option value. They can also have a single “-“, if the short version is used. Instead of using --revision it’s possible to just use -r.

The arguments are sometimes optional and are separated using a space. It depends on the subcommand.

Let’s see how it works. Enter svn help to get a list of commands. Now you can get more info by adding a subcommand as argument for help: svn help checkout. It’s quite helpful to get some quick documentation.

General commands #
First off, I’ll explain the general all-day commands.

We should start with the most important: checkout. You already should know what it does; now how do we use it in cli? The checkout subcommand takes two parameters. First is the svn repository, second is the folder we want to check out to. “.” is the current folder (for your information, “..” refers to the parent directory, this can be useful if you want to cd one level up: cd ..), but we want to check out into a new folder, not the current. So let’s checkout a copy of phpBB 3.1. The following will do a checkout into a new folder called “phpbb”

Code: Select all

svn checkout http://code.phpbb.com/svn/phpbb/trunk/phpBB/ phpbb

We should now get a long long list of files that are added to our working copy. It will take a while to check out, should be less than a minute though. At the end of the list I have:

Checked out revision 8475.

Now we’re still in c:\work, let’s cd into our working copy. cd phpbb.

If you have a private repository, a password will be required, so you’ll have to enter:

Code: Select all

svn checkout --username <username> --password <password> <repository path> <folder>

By the way, by default svn will save your passwords, so you only have to enter them once.

Now, let’s assume one of the phpbb developers committed some changes and our working copy is out of date. So let’s do an update. You need to be in the working copy to do this.

Code: Select all

svn update

That’s all, svn will do the rest.

Okay, what if we have our own repository? Now we changed some files and want to do a checkin (commit). So let’s do:

Code: Select all

svn ci --message “fixing bug xy”

That’s all you need to do.

How about if we want to add a file? Let’s say we added a file called “license.txt”. It’s already in the working copy folder, but not yet added. So we need to use add.

Code: Select all

svn add license.txt

After that you have to commit to add it definitely.

Property commands #
You already learnt (yes, that is correct spelling) about properties in the last article. Now let’s see how this works in CLI.

To see what properties a file has, you can use proplist. It lists the properties that are set, but not their values. Here’s an example:

Code: Select all

svn proplist install.txt

That returns the following for me:

C:\work\troll>svn proplist install.txt
Properties on 'install.txt':
svn:keywords

If you want the value, you use propget, like this:

Code: Select all

svn propget svn:keywords install.txt

For me that returns:

Id

Let’s say I want to change the property or add one. For this we use propset.

Code: Select all

svn propset svn:keywords “Id Rev” install.txt

Which gives me:

C:\work\troll>svn propset svn:keywords "Id Rev" install.txt
property 'svn:keywords' set on 'install.txt'

Whoops, actually I didn’t want that property in the first place. So let’s propdel it.

Code: Select all

svn propdel svn:keywords install.txt

And that gives me:

C:\work\troll>svn propdel svn:keywords install.txt
property 'svn:keywords' deleted from 'install.txt'.

Now we know how to handle properties in SVN. But the way proplist works is really awful, because it doesn’t give us the values. What a pain! But wait, the guys who made svn are simply genius, they added an option called “verbose”, so what you can do is:

Code: Select all

svn proplist --verbose install.txt

Which would give you:

C:\work\troll>svn proplist --verbose install.txt
Properties on 'install.txt':
svn:keywords : Id

File commands #
There are also commands to handle files and dirs, anybody who’s worked with a linux shell will know the first one, it’s ls, which is also known as “list” (in svn) or “dir” (in windows), it lists a directory’s files:

Code: Select all

svn ls

Which returns this for me:

Code: Select all

C:\work\troll>svn ls
develop/
install.txt
install.xml
license.txt
modx.prosilver.en.xsl
root/

In case you’ve not noticed, I’m using my troll mod as an example for this.

Now, what if we want to see the contents of a file, for this there is (like in unix) cat, which can in certain cases also be an animal with four legs and fur that can be found in many households .

Code: Select all

svn cat install.txt

I’ll not include the output, the article is long enough as it is, it’s simply the contents of the file. Now what is this useful for? First of all, you can get the contents of an old revision of a file, like this:

Code: Select all

svn cat -r <revision> install.txt

Now, the command line has the possibility to save the output in a file. This is done using “>”. More exact, like this:

Code: Select all

<some command> > <filename>

So, I could do:

Code: Select all

svn cat –r 30 install.txt > install_r30.txt

Which would save it in a file called install_r30.txt.

Interesting, copy. The main reason this is used is to create a new branch or to tag a release. To do this you’d do:

Code: Select all

svn mkdir tags/1.0.0
svn copy trunk/install.txt tags/1.0.0/install.txt
svn copy trunk/root tags/1.0.0/root
svn copy trunk/develop tags/1.0.0/develop

If you are as intelligent like the phpbb guys, who have it all in a subfolder (called “phpBB”, then you can do:

Code: Select all

svn copy trunk tags/1.0.0

Then there’s rename, which is also known as “move” (I personally think rename makes more sense). It can happen from time to time that a path in your repository changes, or just a filename. In this case you can simply do:

Code: Select all

svn rename gpl.txt license.txt

Which will rename (move) the file.

Last but not least (of the file commands), there’s delete, which is used to delete a file (what a surprise). Have an example:

Code: Select all

svn delete root/includes/functions_troll_admin.php

Info commands #
The following commands will tell you a little more about your repository, files and folders.

First, info.

Code: Select all

C:\work\troll>svn info
Path: .
URL: http://svn2.assembla.com/svn/evilmods/3.0/troll/trunk
Repository Root: http://svn2.assembla.com/svn/evilmods
Repository UUID: 8f7cbc4e-d821-48fb-b665-6de9fca9247a
Revision: 66
Node Kind: directory
Schedule: normal
Last Changed Author: evil3
Last Changed Rev: 66
Last Changed Date: 2008-03-26 17:47:57 +0100 (Mi, 26 Mrz 2008)

You can get this info for any file in your working copy, just specify it as argument.

Now, if you want to know about which files are modified for example, you can use status. It’s recursive, so you can just do:

Code: Select all

svn status

And in my case it returns that I have one “un-added” and one modified one:

Code: Select all

C:\work\troll>svn status
?      install_r30.txt
 M     install.txt

The help command you already know, I won’t explain any more about it.

Now, the log command. As you probably know, every revision has a log message. With the log command you can view it, but before you go entering svn log, you may want to know about the “limit” option. Else you might be getting hundreds or thousands of log messages.

Code: Select all

svn log --limit 10

Well, that returns the log messages. Not bad! But I want to know more about the revision, what files were changed?

Code: Select all

svn log --limit 10 –verbose

Yay .

Advanced commands #
They just didn’t seem to fit into the other categories. I think I’ll start with one of the coolest svn commands altogether: diff.

Have you ever wanted to know the difference between to revisions of a file? Or did you suscribe to the phpbb svn checkin mailing list, which sends out the diffs of each checkin? Now you are able to make your own diffs!

Before I start, I’ll cd into the root of my MOD, where I have branches, tags and trunk. Now I’m just about to release version 1.0.1 of my MOD. But first I want to have update instructions. To create them easily, I just look at a diff of my files. Now, let’s do the following:

Code: Select all

svn diff tags/1.0.0 trunk

And there – we already have our changes! Now wasn’t that easy?

Okay, now let’s say we have a working copy and changed some things, and we want to see what is changed. All you have to do is:

Code: Select all

 svn diff

It will by default give you a diff of the changed working copy against the base (unmodified working copy).

Another thing you may sometimes use is revert. Let’s say you changed some things by mistake and want to undo your changes. All you have to do is:

Code: Select all

svn revert <filename>

This will revert that file. If you want to revert all files, you can use the --recursive option, like this:

Code: Select all

svn revert --recursive .

That will revert anything you changed.

Using SVN remotely #
One of the great things about SVN is how it can be used to access the repository directly. You can even perform move actions directly, by specifying the repository URL as an argument. But I prefer to do those things via working copy. But here’s something really cool:

Code: Select all

svn diff http://code.phpbb.com/svn/phpbb/tags/release_3_0_0/ http://code.phpbb.com/svn/phpbb/tags/release_3_0_1-RC1/

For more info, look in the SVN documentation linked at the top of this article.

I hope you found it useful!