1. Subversion (SVN) Cook Book
    1. How do I install the Subversion?
    2. I want to use Subversion in Windows.
    3. How do I create a subversion repository?
    4. I forget the command line options.
    5. How do I create an initial folder structure?
    6. What folder layout should I use?
    7. How do I add a new file?
    8. How do I add a new folder?
    9. How do I keep my working copy up-to-date?
    10. I made a mistake in editing a file. How do I cancel my modification to the …
    11. How do I take a backup of my repository?
    12. How do I restore the repository from the dump file?
    13. How do I get the revision number or other information of my working …
    14. How do I remember to perform 'svn add' for newly created files?
    15. How do I setup web-based subversion repository?
    16. I need an archive of my subversion repository, which does not contain .svn …

Subversion (SVN) Cook Book

Written by Taro L. Saito.

This article is a quick start guide for the basic usage of Subversion, which is a version management system of your files and directory structures. Subversion keeps tracks of your modifications to files and directories, so you can safely edit your source codes or documents without caring about information loss of your valuable efforts. Subversion is a powerful tool for accomodating rapid changes of your source codes and for facilitating your development and refactoring routines.

How do I install the Subversion?

Follow the official instruction for your OS: http://subversion.tigris.org/project_packages.html

I want to use Subversion in Windows.

Use TortoiseSVN http://tortoisesvn.tigris.org/, which extends the Explorer (File/Folder Viewer) so that you can use Subversion from the right-click menu.

How do I create a subversion repository?

Use svnadmin command: 

 > svnadmin create (path to your repository)

I forget the command line options.

Use --help switch. 

leo@iris:~/tmp/subversion/work> svnadmin --help      
general usage: svnadmin SUBCOMMAND REPOS_PATH  [ARGS & OPTIONS ...]
Type 'svnadmin help <subcommand>' for help on a specific subcommand.
Type 'svnadmin --version' to see the program version and FS modules.

Available subcommands:
   crashtest
   create
   deltify
   dump
   help (?, h)
   hotcopy
   list-dblogs
   list-unused-dblogs
   load
   lslocks
   lstxns
   recover
   rmlocks
   rmtxns
   setlog
   verify

Display subcommand-specific help messages: 

leo@iris:~/tmp/subversion/work> svnadmin create --help
create: usage: svnadmin create REPOS_PATH

Create a new, empty repository at REPOS_PATH.

Valid options:
  --bdb-txn-nosync         : disable fsync at transaction commit [Berkeley DB]
  --bdb-log-keep           : disable automatic log file removal [Berkeley DB]
  --config-dir arg         : read user configuration files from directory ARG
  --fs-type arg            : type of repository: 'fsfs' (default) or 'bdb'
  --pre-1.4-compatible     : use format compatible with Subversion versions
                             earlier than 1.4

How do I create an initial folder structure?

Suppose that you have created the following subversion repository, named 'repo'. 

leo@iris:~/tmp/subversion> svnadmin create repo 
leo@iris:~/tmp/subversion> ls
repo/

First, checkout the root folder from the subversion repository: 

leo@iris:~/tmp/subversion> mkdir work
leo@iris:~/tmp/subversion> cd work 
leo@iris:~/tmp/subversion/work> svn checkout file:///Users/leo/tmp/subversion/repo project
Checked out revision 0.
leo@iris:~/tmp/subversion/work> ls
project/

A path to the subversion repository must begin with file:///, followed by the absolute path to your svn repository. We call the project folder working directory.

Then, create trunk, branches, tags directories: 

leo@iris:~/tmp/subversion/work> cd project 
leo@iris:~/tmp/subversion/work/project> ls
leo@iris:~/tmp/subversion/work/project> mkdir trunk branches tags

Use svn add to add these folders into the repository: 

leo@iris:~/tmp/subversion/work/project> svn add trunk branches tags 
A         trunk
A         branches
A         tags

This command affects only the state of your working copy (the project folder), not that of your svn repository.

Finally, use svn commit command to make the change permanent: 

leo@iris:~/tmp/subversion/work/project> svn commit -m 'created an initial folder structure' 
Adding         branches
Adding         tags
Adding         trunk

Committed revision 1.

'-m' option sets the associated log message to the revision.

What folder layout should I use?

Follow this guideline: 

  trunk:     main folder for the development. 
             Contents in this folder must be correctly compiled and pass tests.
  branches:  temporary folder
  tags:      put stable versions in this folder

Or, you can use project-by-project layout: 

  project1/trunk
  project1/branches
  project1/tags
  project2/trunk
  project2/branches
  project2/tags
  ...

How do I add a new file?

Create a file in your working direcotry, then use 'svn add', and 'svn commit': 

leo@iris:~/tmp/subversion/work/project/trunk> echo Hello World > Hello.txt
leo@iris:~/tmp/subversion/work/project/trunk> cat Hello.txt 
Hello World
leo@iris:~/tmp/subversion/work/project/trunk> svn add Hello.txt 
A         Hello.txt
leo@iris:~/tmp/subversion/work/project/trunk> svn commit Hello.txt -m 'added a new file' 
Adding         Hello.txt
Transmitting file data .
Committed revision 2.

How do I add a new folder?

Create a folder (and several files), then use 'svn add', and 'svn commit' 

leo@iris:~/tmp/subversion/work/project/trunk> mkdir doc

leo@iris:~/tmp/subversion/work/project/trunk> touch doc/README
leo@iris:~/tmp/subversion/work/project/trunk> touch doc/LICENSE
leo@iris:~/tmp/subversion/work/project/trunk> ls
Hello.txt  doc/
leo@iris:~/tmp/subversion/work/project/trunk> ls doc
LICENSE  README
leo@iris:~/tmp/subversion/work/project/trunk> svn add doc 
A         doc
A         doc/LICENSE
A         doc/README
leo@iris:~/tmp/subversion/work/project/trunk> svn commit -m 'added a new folder'
Adding         trunk/doc
Adding         trunk/doc/LICENSE
Adding         trunk/doc/README
Transmitting file data ..
Committed revision 3.

Note that 'svn add' command recursively adds sub folders and files.

How do I keep my working copy up-to-date?

Use 'svn update': 

leo@iris:~/tmp/subversion/work/project/trunk> svn update
At revision 3.

Even if you unintentionally deleted some files in your working directory, 'svn update' command will recover missing files from the repository: 

leo@iris:~/tmp/subversion/work/project/trunk> rm Hello.txt doc/LICENSE 
leo@iris:~/tmp/subversion/work/project/trunk> svn update
Restored 'Hello.txt'
Restored 'doc/LICENSE'
At revision 3.

I made a mistake in editing a file. How do I cancel my modification to the file?

Use 'svn revert': 

(edit the file)
leo@iris:~/tmp/subversion/work/project/trunk> echo Faagasdfadsfaawre32 >> Hello.txt
leo@iris:~/tmp/subversion/work/project/trunk> cat Hello.txt 
Hello World
Faagasdfadsfaawre32

leo@iris:~/tmp/subversion/work/project/trunk> svn revert Hello.txt 
Reverted 'Hello.txt'
leo@iris:~/tmp/subversion/work/project/trunk> cat Hello.txt 
Hello World

How do I take a backup of my repository?

Use 'svnadmin dump' command: 

leo@iris:~/tmp/subversion> svnadmin dump repo > repo.svndump
* Dumped revision 0.
* Dumped revision 1.
* Dumped revision 2.
* Dumped revision 3.

The repo.svndump file can be used to restore your reposiotory from scratch. Keep your dump file in a safe place.

How do I restore the repository from the dump file?

Create a new repositoy, then load the dump file into the new repository using 'svnadmin load' command: 

leo@iris:~/tmp/subversion> svnadmin create newrepo
leo@iris:~/tmp/subversion> svnadmin load newrepo < repo.svndump 
<<< Started new transaction, based on original revision 1
     * adding path : branches ... done.
     * adding path : tags ... done.
     * adding path : trunk ... done.

------- Committed revision 1 >>>

<<< Started new transaction, based on original revision 2
     * adding path : trunk/Hello.txt ... done.

------- Committed revision 2 >>>

<<< Started new transaction, based on original revision 3
     * adding path : trunk/doc ... done.
     * adding path : trunk/doc/LICENSE ... done.
     * adding path : trunk/doc/README ... done.

------- Committed revision 3 >>>

Now, the 'repo' and 'newrepo' repositories has the same contents.

How do I get the revision number or other information of my working directory?

Use 'svn info': 

leo@iris:~/tmp/subversion/work/project/trunk> svn info
Path: .
URL: file:///Users/leo/tmp/subversion/repo/trunk
Repository Root: file:///Users/leo/tmp/subversion/repo
Repository UUID: 3305defb-2552-41ed-b507-21250eecb431
Revision: 3
Node Kind: directory
Schedule: normal
Last Changed Author: leo
Last Changed Rev: 3
Last Changed Date: 2007-11-21 15:58:17 +0900

How do I remember to perform 'svn add' for newly created files?

Use 'svn status' command: 

leo@iris:~/tmp/subversion/work/project/trunk> ls
Hello.txt  doc/
leo@iris:~/tmp/subversion/work/project/trunk> touch Hello2.txt
leo@iris:~/tmp/subversion/work/project/trunk> svn status
?      Hello2.txt
leo@iris:~/tmp/subversion/work/project/trunk> svn add Hello2.txt

How do I setup web-based subversion repository?

A solution is to use apache + mod_dav_svn.

Install subversion, httpd, mod_dav_svn: 

 > sudo yum install subversion
 > sudo yum install httpd
 > sudo yum install mod_dav_svn

Suppose we have three svn repositories: repo, privaterepo and publicrepo in the /home/svn/repository folder. The 'repo' repository allows only developers (leo and ahsan) to read and modify this contents, and 'privaterepo' is only for user 'leo'. The 'publicrepo' is readable to anyone from the web.

An example of /etc/httpd/conf.d/subversion.conf. 

LoadModule dav_svn_module     modules/mod_dav_svn.so
LoadModule authz_svn_module   modules/mod_authz_svn.so

<Location /svn>
   AddType text/x-server-parsed-html .html
   DAV svn
   SVNParentPath /home/svn/repository
   AuthType Digest
   AuthName "Subversion Authentication"
   AuthUserFile (absolute path to the .htdigest file)
   Satisfy Any
   Require valid-user
   AuthzSVNAccessFile (absolute path to the .svnaccess file)
</Location>

Edit paths to .htpasswd and .svnaccess files according to your environment.

.svnaccess file 

[groups]
developers = leo ahsan

[repo:/]
@developers = rw
* = 

[privaterepo:/]
leo = rw
* = 

[publicrepo:/]
leo = rw
* = r

Create .htdigest file: 

 > htdigest -c .htdigest 'Subversion Authentication' leo 
 (enter password for leo)

Add a new user: 

 > htdigest .htdigest 'Subversion Authentication' ahsan
 (enter password for ahsan)

Restart the httpd server: 

 > sudo /etc/init.d/httpd restart

Confirm your svn repositories are visible from the following URLs: 

 * http://(your web server's domain)/svn/repo
 * http://(your web server's domain)/svn/privaterepo
 * http://(your web server's domain)/svn/publicrepo

Now, we are ready to use these above URLs in the subversion commands: 

 > svn checkout http://yourserver.domain/svn/repo/trunk myproject
 > svn checkout http://yourserver.domain/svn/privaterepo/trunk private_project
 > svn checkout http://yourserver.domain/svn/publicrepo/trunk public_project

I need an archive of my subversion repository, which does not contain .svn folders.

Use 'svn export' command: 

leo@iris:~/tmp/subversion/work/archive> svn export file:///Users/leo/tmp/subversion/repo repo  
A    repo
A    repo/trunk
A    repo/trunk/Hello.txt
A    repo/trunk/doc
A    repo/trunk/doc/LICENSE
A    repo/trunk/doc/README
A    repo/branches
A    repo/tags
Exported revision 3.