Rob's Favorite Subversion (svn) Commands

Creating a repository

Incredibly easy, as the manual says. Just enter:

  svnadmin create /path/to/repos

Then once the new repository is created, it is easy to check it out and then start adding files to it. First, on the host computer:

  svnadmin create ~/svnroot/teaching

Then go to a remote computer and check out a copy with

  svn co svn+ssh://svn.cvrti.utah.edu/Home/myusernameid/svnroot/teaching Teaching
  cd Teaching
  cp files .
  svn add files
  svn commit -m "adding new files"

To create a repository that is to be shared by other users (with accounts on the same computer as the repository) there are some additional steps.

Ensure that the other users of the repository have accounts on the repository computer AND
make sure they are all members of one group, in this example, the "svn" group.
Log into the repository computer and cd to the root directory
```
  cd ~/svnroot  
```
Make sure umask is 002 (e.g., execute the "umask 002" command)
```
  umask 002  
```
Create the repository as usual, e.g.,
```
  svnadmin create ~/svnroot/afib-nih09 
```
Change the group of all the directories in the repositiory, e.g.:
```
  chgrp -R svn afib-nih09/ 
```

Checking out a repository

Standard checkout from remote repository
```
 svn co svn+ssh://machine_name/dirname local_dirname
```
This will place the files in "local_dirname" in a local directory under a trunk directory that it will create if necessary.
Standard checkout from local repository
```
 svn co file:///Path/To/Repository/dirname local_dirname
```
This does the same as above but looks in the local computer for the repository according to the path specified, e.g.,
```
 svn co file:///Home/macleod/svnroot/torso 
```
to check out my torso directory when logged into the svn host computer.
Another example:
```
       svn co svn+ssh://svn.cvrti.utah.edu/Home/svn/map3d/trunk map3d 
    
```
places all the files from map3d into a local subdirectory map3d,
```
       svn co https://code.sci.utah.edu/svn/map3d/trunk map3d
    
```
does the same thing but from a different repository that does not require ssh access.
and
```
	cd ~/roblibs
	svn co svn+ssh://svn.cvrti.utah.edu/Home/macleod/svnroot/roblibs/trunk .
      
```
places all the contents of the roblibs repository into the current local directory called roblibs.
```
        svn co svn+ssh://svn.cvrti.utah.edu/Home/macleod/svnroot/www www
    
```
checks out my full web site and puts it in the local "www" directory, wherever that sits at the time of checkout. Note that there is no trunk directory in this case, which is an option at the time of setting up that respository.

For files that are buried below a respository name, you must identify the specific library, e.g.,

      cd 
       svn co svn+ssh://svn.cvrti.utah.edu/Home/svn/glibs/cutil/trunk cutil

Note that at CVRTI, glibs contains: cutil, fi, fids, gdbmp, gfilelib, numseq, and tsdflib so a complete checkout looks like this:

      cd 
       svn co svn+ssh://svn.cvrti.utah.edu/Home/svn/glibs/cutil/trunk cutil
      cd ~/tedutils
       svn co svn+ssh://svn.cvrti.utah.edu/Home/svn/glibs/fi/trunk fi
       svn co svn+ssh://svn.cvrti.utah.edu/Home/svn/glibs/numseq/trunk numseq
      cd ~/dfile
       svn co svn+ssh://svn.cvrti.utah.edu/Home/svn/glibs/fids/trunk fids
       svn co svn+ssh://svn.cvrti.utah.edu/Home/svn/glibs/gdbmp/trunk gdbmp
       svn co svn+ssh://svn.cvrti.utah.edu/Home/svn/glibs/tsdflib/trunk tsdflib
       svn co svn+ssh://svn.cvrti.utah.edu/Home/svn/dataio/graphicsio/trunk graphicsio
       svn co svn+ssh://svn.cvrti.utah.edu/Home/svn/dataio/MatlabIO/trunk MatlabIO
      cd ~/dfile
       svn co svn+ssh://svn.cvrti.utah.edu/Home/svn/glibs/gfilelib/trunk lib

Adding, deleting, moving files

Always tell svn when you add or otherwise change the contents of the repository.

   svn add filename/directory-name

adds files or directories. The directory must already exist and when added, it will (be default) add all the contents of the directory.

When adding a binary file, i.e., on that contains more than just plain text, an additional command can reduce the overhead of carrying out diff operations each time these files are updated:

   svn add filename(s)
   svn propset svn:mime-type application/pdf filename(s)

To remove a file, both from your local directory and the repository, enter the following:

   svn rm filename/directory-name

When done with adding, deleting, and moving, it is necessary to commit the changes with

    svn commit -m "message_text"

Checking status

To check the status of the local version against the repository, use the commands svn status and svn diff, e.g.

    svn status

will return a list of files that have changed or are otherwise interesting. The meaning of the code letters to the left of each file are as follows:

M filename: the local file has changed (and needs committing)
? filename: the file is not part of the svn repository
A filename: the file is scheduled for addition (do an update)
D filename: the file is scheduled for deletion
C filename: the file has a conflict that needs resolving
~filename: the file exists locally and in the repository but is a different type of file in the two places
* filename: there is a newer version of the file in the repository

   svn status -u

Stands for --show-updates and will talk to the repository and show changes relative to it; otherwise, status only looks locally.

Resolving conflicts

When changes happen in two different versions or local copies of the file, there can be conflicts. When svn cannot work out those conflicts automatically, it places the two temporary copies of the conflicting versions in the local directory along with the older version---so there are three copies of what should be the same file. To resolve a conflict, do one of three things:

Merge the conflicted text "by hand" (by examining and editing the conflict markers within the file).
Copy one of the temporary files on top of your working file.
Run
```
 svn revert filename 
```
to throw away all of your local changes.

Whichever root taken, it is necessary to let Subversion know by running

      svn resolved  filename

This removes any three temporary files and Subversion no longer considers the file to be in a state of conflict.

Getting information about a repository

info command

Often it is nice find out where a repository was from which a project has come. This and other info is available by means of the info command, e.g.,

    svn info

will return information about the repository of the project in the current directory, e.g.,

  Path: .
  URL: https://code.sci.utah.edu/svn/map3d/trunk
  Repository Root: https://code.sci.utah.edu/svn/map3d
  Repository UUID: 76038eab-591d-0410-bf0b-a17c1341c730
  Revision: 29
  Node Kind: directory
  Schedule: normal
  Last Changed Author: macleod
  Last Changed Rev: 29
  Last Changed Date: 2007-02-27 14:45:08 -0700 (Tue, 27 Feb 2007)

ls command

The command

    svn ls

provides a listing of the contents of a repository, much like the same command works in Unix. Simply go to the directory that is under svn control and enter svn ls, e.g.,

  cd ~/www/docs
  svn ls

You may be prompted one or more time for the password of the repository but eventually there will be a list of the files and directories as the level of the current working directory. To get a high level view of the repository, enter the following command:

  svn ls full_repository_path

where full_repository_path is whatever you are using, e.g.,

  svn ls file:///Home/macleod/svnroot/www

The "-v" option will add more detail to any svn ls command.

svnlook command

The command svnlook is what provides access to the database containing the repository files; otherwise, there is not real way to examine a repository, unlike the CVS repositories. For example, the command

   svnlook tree ~/svnroot/www | more

will reveal the contents, down to the files, of the entire www repository in my svnroot area. The output is long, hence the more command.

   svnlook tree ~/svnroot/roblibs | more

does the same for another repository of mine that actually contains several pieces, including cutil, fids, and gfilelib. This repository also contains the full set of trunk, branches, and tags organization that is the standard svn way of doing things for code development.

Cleanup command

Often there are locked files that end up hanging around when an operation is interrupted. To deal with the error messsage

   svn: Working copy '/Users/macleod/www' locked

Then run the cleanup command but always FROM THE TOP LEVEL OF THE REPOSITORY!!!. In the case above, I went to the ~/www and ran the command, e.g.,

   cd ~/www
   svn cleanup

and it seemed to work.

Locking Files

Unlike CVS, svn allows locking of files! The mechanism is simple and transparent.

To lock a file in a repository:

Make sure the working copy is up to date with an
```
svn up
```
command.

Lock the desired file(s) with the command

   svn lock file_names  -m "optional comment"

Go about editing the file as usual.
When editing is complete, check in the new version and release the lock with the usual commit command:
```
   svn commit file_names  -m "optional comment"
```
Note that this will unlock ALL files in the directory, not just the one(s) that have changed.
If you wish to keep the files locked after committing, add the
```
 --no-unlock
```
option to the command:
```
   svn commit file_names  -m "optional comment" --no-unlock
```
To imply unlock file without checking it back in
```
   svn unlock file_names  
```

Any user trying to change the file will be blocked with an error message. To discvoer status of a file, use the following command:

   svn status -u

and look for an "O" (stands for owned by Others) in the entry for any locked files. To see who has locked the file, use the info command

   svn info file_names

Migrating repositories

You can hope you never have to do this but it can happen and the commands are not too awful.

Taking the contents of one repository and moving it another happens like this:

Dump the contents of the existing repository into a portable file:
```
      svnadmin dump my_repos > my_repos_file
    
```
At the end of which there will be a new file names my_repos_file (can be any filename)

Load this portable file into a new existing repository.

	svnadmin load my_new_repos < my_repos_file