Subversion Commands and Scripts

Tutorial Contents:

• # Subversion Introduction
• # Subversion Commands
• # Subversion content properties
• # Subversion and Graphical diffs
• # Subversion GUI interface
• # Subversion Security Tips
• # Subversion utility commands and scripts
• # Subversion Best Practices
• # Links
• # Books

Related YoLinux Tutorials:

°Subversion Server and Trac Server Installation and Configuration

°Subversion Repository Transfer

°Cabie Automated Builds and Subversion

°Software development tools

°Clearcase Commands

°Clearcase Client Install

°Clearcase Server Install

°Subversion vs Clearcase

°CVS Intro

°RCS Intro

°C++ Info, links

°Java on Linux

°YoLinux Tutorials Index

Free Information Technology Magazine Subscriptions and Document Downloads

Free Information Technology Software and Development Magazine Subscriptions and Document Downloads

Subversion is a software source code "Change Management" (CM) system for collaborative development. It maintains a history of file and directory versions. The files and directories are checked out of the repository and into your local project work area. This called your "working directory". Changes are made to files in your "working directory". After changes are made to the create the next working version, the files are checked into the Subversion CM repository.

Where RevisionNumber is:

• HEAD: The latest revision in the repository.
• BASE: The "pristine" revision of an item in a working copy. Matches checked out version before any modifications.
• COMMITTED: The last revision in which an item changed before (or at) BASE.
• PREV: The revision just before the last revision in which an item changed. (Technically, COMMITTED - 1.)

Example Session:

• Checkout: svn checkout http://svnserver/repos/svn/trunk/Project1
• Go to source code directory: cd Project1/src
• Edit files:
  • vi file1.cpp
  • vi file2.cpp
• Verify and test: make
  We are ready to check-in the files into the Subversion repository.
• Check repository and report on new revisions and changes others have checked in: svn status -u .
• After many long hours or days of editing and work, get updates others have made: svn update

      U file.h
      C file1.cpp
      G file2.cpp
      ? a.out 

  You will see:
  • U: File was updated with a newer version checked-in since your checkout.
  • G: Automatically merged with no conflicts.
  • C: Not merged due to conflicts. You made changes to the same section of code as the update made by someone else since your checkout.
• For each "conflicted" file there will be three new local files generated by "update":
  • file1.cpp.mine (File - post editing)
  • file1.cpp.rold (BASE - pre editing)
  • file1.cpp.rnew (HEAD - Updated file from repository)
  The file file1.cpp still exists but with svn conflict marker strings added in the file.
  At this point, a check-in will fail until the merge is resolved.
• Merge options:
  • Edit the file file1.cpp
    Text markers are placed in the file to show the conflicts between the "HEAD" and "mine" versions.
    OR
  • tkdiff -conflict file1.cpp
    OR
  • Use a GUI merge tool: kdiff3 file1.cpp.mine file1.cpp.rnew -o file1.cpp
    OR
  • Throw out your changes/abort: svn revert file1.cpp
    No resolve or check-in necessary if file is reverted.
• Verify and test, again: make
• Notify Subversion that conflicts have been resolved: svn resolved file1.cpp
  Note: This also removes the temporary files ".mine" and ".r###".
• Check-in to Subversion repository: svn ci -m "Add comments here" file1.cpp

Files under revision control can include Subversion keywords which properties can be set with the "propset" command. Keywords are substituted with the Subversion properties and will not appear in the file until a commit is performed. Other properties are used to modify the behavior of Subversion.

The following properties can be set on entities stored in Subversion:

/* $URL$
   $Rev$
   $Author$
   $Date$
   $Id$
 */
                     

/* $URL:http://server/svn/path/file.cpp $
   $ Rev:2 $
   $ Author:Greg $
   $ Date:2006-10-12 14:31:84 -0400 (Thu,12 Oct 2006)$
   $ Id:file.cpp 3 2006-10-12 18:31:84Z Greg $
 */
                     

Three types of file differences are covered in this section:

1. Show file differences made since checkout was made. This shows the changes you have made. It is usefull to perform this before an update.
2. Show file differences between two files versions stored in Subversion.
3. Show differences / conflicts, choose and merge. Use our bash script svndiffwrapper which integrates into Subversion's file check-in process.

The following scripts will allow you to view the changes you have made since checkout. Use the script before running "svn update" as an update will alter the file with diff chevron (>>>>) markers. After performing a "svn update", use tkdiff, gtkdiff or kdiff3 as described below instead of the scripts:

Use the following bash shell script to use the graphical diff tool "mgdiff" with Subversion.

svndiff:

#!/bin/bash # svndiff 1.0 # usage: svndiff file if [[ ! -d .svn ]] then echo ERROR: You are not working in an SVN directory. exit 1 fi rev="--revision HEAD" if [[ ! -n $1 ]] then echo "Usage: svndiff [option] file" echo "Options:" echo " -h Diff with latest in repository (HEAD) - Default" echo " -b Diff with what you had checked out (BASE)" echo " -c Diff with COMMITTED, the version before BASE" echo " -p Diff with PREV, the version before COMMITTED" echo " -r revnum Diff with specified revision (specify integer)" exit 1 fi while getopts ":r:hbcp" Option do case $Option in h) rev="--revision HEAD";; b) rev="--revision BASE";; c) rev="--revision COMMITTED";; p) rev="--revision PREV";; r) rev="--revision $OPTARG";; *) echo "Incorrect option specified. Use -h or -b or -r #";; esac done shift $(($OPTIND -1)) # Define graphical diff tool # # The geometry option used by Motif, Tcl and X based programs geometry="-geometry 1280x800+0+0" # The following is for Motif diff # -w: ignore white space dif="mgdiff -args -w" file=$1 prev=${file}_PREV # Trap bash command signals # SIGINT 2 # SIGQUIT 3 # SIGTERM 15 trap "rm -f $prev" 2 3 15 svn cat $rev $file > $prev 2>/dev/null $dif $geometry $prev $file sleep 1 rm -f $prev

Compares your current local copy with the latest in the repository (Default "-h").

OR

Use the following bash shell script to use the graphical diff tool "gvimdiff:" with Subversion:

svndiff:

#!/bin/bash # usage: svndiff file if [[ ! -d .svn ]] then echo ERROR: You are not working in an SVN directory. exit 1 fi # Define graphical diff tool # dif="gvimdiff \"+colo morning\" -R" file=$1 prev=PREV_${file} # Trap bash command signals # SIGINT 2 # SIGQUIT 3 # SIGTERM 15 trap "rm -f $prev" 2 3 15 svn cat $file > $prev 2>/dev/null $dif $prev $file # Sleep for non-blocking apps like gvimdiff. # Allow gvimdiff to read file before it is deleted. sleep 2 rm -f $prev

Compare your current local copy with the original copy you checked out.

This configuration supports the use of GUI diff tools with Subversion by using the command: svn diff -r 457:459 --diff-cmd
Some diff tools are supported with native svn. i.e.: svn diff -r 457:459 --diff-cmd kdiff3 file-name while others require a wrapper script to arrange the arguments correctly.

Subversion configurations and defaults are specified in the file: $HOME/.subversion/config

.. ... [helpers] editor-cmd = gedit diff-cmd = /opt/bin/diffScript diff3-cmd = /opt/bin/diff3Script ... ..

This configuration configures Subversion to execute the script /opt/bin/diffScript to launch your own diff toolwith the command: svn diff -r Old:New URL.

File: /opt/bin/diffScript

#!/bin/bash LeftLabel=$3 RightLabel=$5 LeftFile=$6 RightFile=$7 #gtkdiff $LeftFile $RightFile tkdiff $LeftFile $RightFile -L "$LeftLabel" -L "$RightLabel" & # wait for command to finish wait

Note: To debug what is passed as a command line argument to the diff tool, set the diff-cmd to "echo":

.. ... [helpers] diff-cmd = echo ... ..

This configuration echos to the screen the command line arguments being passed to the diff tool when the following command is executed: svn diff .....

i.e. -u -L d0/f01.cpp (revision 1) -L d0/f01.cpp (working copy) d0/.svn/text-base/f01.cpp.svn-base d0/.svn/empty-file

• tkdiff: Subversion conflict resolution merge: tkdiff -conflict file1.cpp
  Select from tkdiff toolbar: "Merge" + "Show Merge Window" to open third results window.

• kdiff3 diff and merge: svn diff -r 457:459 --diff-cmd kdiff3 --extensions '-m' file-name

• svndiffwrapper: Bash script to add options to Merge|Ignore|Accept|Revert etc as a result of a check-in. This script does it all!!

  Edit file: $HOME/.subversion/config

  ... [helpers] diff-cmd = svndiffwrapper diff3-cmd = svndiffwrapper ...

  Use our bash script svndiffwrapper to perform this integrated task. By default, uses kdiff3 for diff tool. Can also specify your own choice of diff tool.
  Place the script in /opt/bin/ for global use or $HOME/bin/ for private user access and set permissions so that script execution is allowed: chmod ugo+x /opt/bin/svndiffwrapper

• tkdiff: [download] Comes with tkcvs Subversion GUI front-end.
  Examples of Subversion diffs with tkdiff: (See: tkdiff --help)
  • tkdiff old-URL@revA new-URL@revB
  • tkdiff -r457 -r459 file-name
  Note: Use command "svn log file-name" to view valid revision numbers for the file. Referencing invalid revision numbers as input to tkdiff will not work.
• gtkdiff: Has diff3 and merge features. Written with GTK+. After gtkdiff-0.8.0, GNOME desktop required.
• diffUse: Diff/merge GUI tool. Good line matching features. Supports Unicode.
• kdiff3: Graphical directory and file diff, merge and edit. KDE3/Qt based. Supports drag and drop. Comes with S.u.S.E. distro. (Cross platform) MS/Windows download available. A very good directory and file diff and merge tool.
  • Difference: kdiff3 file1 file2
  • Difference: kdiff3 file1 file2 file3
  • Difference of two files: kdiff3 directory1/file directory2
  • Difference: kdiff3 directory1 directory2
  • Merge: kdiff3 directory1 directory2 -o dest-directory
  • Merge: kdiff3 file1 file2 -m
  • Merge: kdiff3 file1 file2 -o output-file
  • Diff with SVN: svn diff -r 457:459 --diff-cmd kdiff3 file-name
• Kompare: Ships with (RHEL4/FC3) KDE SDK. [manual]
• mgdiff: [download] Motif-based graphical file difference browser and merge. Comes with S.u.S.E. distro.
• Meld: Compare, edit and merge.
• fldiff: Graphical file and directory diff. (Cross platform)
• xxdiff: Compare 2 or 3 files and merge. Also compares directories.
• gvim and gvimdiff

• TkSVN / TkCVS: Tcl/Tk based GUI. A very good Unix/Linux and MS/Windows GUI front-end to Subversion. Simple to install (requires tk). Supports GUI diff/merge, branching, tagging, editing, check-in/check-out, ...
  Installation to /usr/local/bin and lib (Add to your path.): (requires RPM: tk version 8.4+)
  • tar xzf tkcvs_8_0_3.tar.gz
  • cd tkcvs_8_0_3
  • ./doinstall.tcl -nox /opt
  Configuration: (See: ~/.tkcvs)

  Set default editor and diff tool:

  ... set cvscfg(editor) "xterm -e vim" set cvscfg(tkdiff) "tkdiff"

  Also see default config file: /opt/lib/tkcvs/tkcvs_def.tcl
  Sets default editors for various file types. Set editor to "gedit" for rookies.

  If you want to run TkSVN / TkCVS on MS/Windows, download Tk for MS/Windows. It can also be run from the Cygwin environment using Tk provided in the Cygwin shell.
• Tigris.org: RapidSVN: Dependent on wxWidgets cross platform C++ GUI API.
  Download RPMs from Dag Wieers:
  • rapidsvn-0.7.2-1.2.el4.rf.i386.rpm
  • wxGTK-2.4.2-5.2.el4.rf.i386.rpm
• pysvn: Python subversion front-end. (cross platform) [download]
• eSVN: qt based GUI. Mediocre.
• KdeSvn: KDE front-end.
• Subcommander: Subversion GUI client with visual diff and merge tool with support for different text encodings
• Subview: GTK based subversion (1.3+) client.
• JSVN: Java SVN client
• Syncro SVN Client - Commercial product. Editor, diff tool and SVN client in one integrated tool.

Web Clients:

• Kamikaze-qscm: Web based front-end similar to Mozilla Bonsai.
• WebClient for SVN: Implemented in JSP for Tomcat 4
• ViewSVN: PHP4
• Easy SVN: PERL cgi

Plug-ins:

• NaughtySVN: GNOME Nautilus file browser SVN plug-in.
• Ksvn: Subversion client plugin for the KDE Konqueror browser.
• Eclipse plug-ins:
  • Tigris.org: subclipse
    Also see: C/C++ development environment and Eclipse
  • Subversive

One should be aware of a possible Subversion client security hole. The Subversion client authentication will cache your login and password in your home directory in non-encrypted clear text. It will have file system security so others can not read the file however, it still is visible by root or by a root user of the file server if one is used for home directories.

Here are three solutions to reduce this potential security vulnerability:

1. Don't allow Subversion to cache the password: svn commit -F file.txt --no-auth-cache
   This will request a username and password but will not store it.
2. Set the Subversion configuration file on server to not cache:

   [auth] store-auth-creds = no

3. Delete cached files when you logout. Reduces risk but does not eliminate it. This uses the bash shell logout script to perform a clean-up of the authentication files.

   File: ~/.bash_logout

   rm ~/.subversion/auth/svn.simple/*

Command	Description
svnversion local-path	This svn admin command will produce a compact version number for a working copy. Lists range of versions, adds "S" if switched, "M" modified.
svnchangesince	Shows the changes to the subversion repository since the local copy was last updated.
svnlastlog	Displays the last log message that pertains to the current working copy. Simplified svnlastchange.
svnlastchange	Displays the last log message and a unified diff of the changes made in the last commit.
svn-clean	Removes all the files and directories that are not in Subversion.

• ALWAYS compile and test before checking in source code. Subversion revisions should correspond to revisions which compile.
• Don't copy, rename and move directories and files with system shell commands. Use Subversion commands to "rm", "mv", and "add" directories and files and then commit changes when done. Work within Subversion.
• Commit changes as a single logical changeset for one purpose. Thus all code changes for a single bug fix or enhancement should be checked-in together. This allows one to better follow the history log of changes.
  • Check-in code at the directory level and all changed files, recursively in the directory and subdirectories will be checked in together.
    svn ci -m "Check-in comment goes here" ./
  • Check-in files together by specifying them explicitly:
    svn ci -m "Check-in comment goes here" file.cpp file2.cpp ...
• Tie Bug tracking and Subversion CM together:
  • Use comments when checking-in files into Subversion. Add bug tracking numbers to the comments so Subversion will reference Trac bugs.
  • If using Trac, add trac comments so that links are generated to the Subversion repository by placing the Subversion revision number in square braces (i.e. [1140]) in a Trac comment. In this way, Trac will have a direct URL link to Subversion.
• If using Trac integrated with Subversion, refer to the Trac ticket in the Subversion check-in comment using a "#" in front of the Trac ticket number (eg. #65) This generates a hyperlink when the Subversion logs are viewed in Trac.
• Taking code from a Subversion repository for upload to another: Use "svn export" and NOT "svn co" if you want files for upload into another CM repository. A checkout (svn co) will create Subversion management directories (.svn/) in the local working copy. You will not want to upload these directories into a CM system as they are only for the user's local working directory only. An "export" will not create these directories.
• The "tags" branches are NOT to be used as working branches but are snapshots of an existing branch. The "tags" are for historical reference such as a release, well tested version or progress milestone.
• Documentation and related artifacts should not be under the source tree but parallel to it. This isolates the source tree so that email notification triggers sent to developers upon source changes will only go out on source changes or regression build and test systems like Cabie will only rebuild and test on source changes rather than on unrelated documentation changes.

• YoLinux Tutorial: Subversion Server and Trac Server Installation and Configuration
• YoLinux Tutorial: Cabie Build System - Installation and Configuration
• svnbook.red-bean.com: Open Sourced version of O'Reily Book
  • Subversion 1.1 - single page
  • Subversion 1.1 - multi-page
• Reference card [pdf] (orig)
• Subversionary: Subversion advocacy web site.
• Integrating JDeveloper and Subversion

Books:

	Version Control with Subversion by C. Michael Pilato ISBN #0596004486, O'Reilly Press
	Practical Subversion (Expert's Voice in Open Source) Garrett Rooney ISBN #1590592905, Apress
	Subversion Version Control: Using the Subversion Version Control System in Development Projects William Nagel ISBN #0131855182, Prentice Hall PTR
	Dr. Dobb's Journal Free subscription to the premier resource for professional programmers and software developers. Multi-language and multi-platform with program listings, coding tips, design issue discussions and algorithms. Subscribe here!	Free Subscription