Guide to SSARC and SSRESTOR

This is a guide to all options of the Microsoft Visual Sourcesafe 6.0 (VSS) archive and restore utilities. If you have any questions, comments, suggestions or corrections please email me at . Also, if you have any good tips on using SSARC or SSRESTOR feel free to email me.

I do hate disclaimers, but it seems necessary for this document: always be very careful when archiving and deleting files. Backing up source files is like voting, do it early and often (warning, this may not be legal in your jurisdiction). I have made an effort to ensure that this document is correct, but there may be errors. Finally, test your backups out before you actually need them, avoid permanent deletes and keep copies in multiple locations.

Sourcesafe is pretty far from perfect, but it is a lot better than nothing and in my experience has worked very well in a single-user environment. I have heard a number of horror stories about Sourcesafe, but they haven't happened to me (*knocks on wood*).

SSARC

Summary

SSARC is used for archiving Microsoft Visual Sourcesafe projects. The official syntax is:

SSARC [-d -v -s -o -i- -y -x -c]

If you are not familiar with the syntax conventions used, < and > are used to delimit arguments. The < and > characters are not typed in. The | means a choice of options. Items enclosed in square brackets, [] are optional, and items not enclosed in square brackets are mandatory.

-d | -d-

Specifiying the -d option will delete from your project the items that you are archiving. This will delete your project from Sourcesafe if you use it! Of course, you can restore from your backup file, but for normal use, and for smaller projects I don't recommend this. This function obviously has its uses, but be sure you want to do this. If the -d- option is used, then SSARC will not delete the projects the items you are archiving. The default is to prompt the user interactively, so if you want to run this from a script, you will need to choose one of the options, or use the -i- flag

-v[D|L]

The -v option lets you archive up to a particular version, according to one of three parameters, -vd, -vl or -v. I have had some difficulty getting this to work properly. The syntax here is quite finicky so I would definitely recommend some careful experimentation before using on real data.

Using neither the D or L option lets you specify a numeric version number.

The D flag allows you do specify a date. -vd1/1/04 would archive everything up to January 1, 2004. This is sort of like the -d option, but gives you more control over the archiving.

The L option lets you specify a project label as the cutoff point, such as "-vlBig Release".

This flag is used to specify the folder of the Sourcesafe database and data. If you use the default settings, then you probably don't need to specify a data path, although you must still include the comma. If the path to your srcsafe.ini file is C:\vss\srcsafe.ini and the data is in the C:\vss\data\ folder, then you would use "-sC:\vss\,". If the data folder was at D:\data\, then you would use "-sC:\vss\,D:\data\".

More infrequently, you can also not specify a srcsafe.ini path, in which case the one specified by your HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\SOURCESAFE\API Current Database key will be used. Finally, you can specify no srcsafe.ini path, and specify a data path, with a comma immediately following the option: -s,D:\data\, which would use the above srcsafe.ini and the data folder at D:\data\

-c | -c-

This is the comment option. Add a parameter such as "-cMy comment" to add a comment about the restore operation to the VSS database. This comment is visible if you do a "Show History" on the restored project (i.e. at the project that you specify with the -p flag of SSRESTOR), in the Details of the item "Restored" item. -c- means that no comment is being given. The default is to ask the user interactively.

-o

Paginate or redirect output. You can specify a text file here, such as "-olog.txt" if you want to copy the messages that the program creates during the archive process to a text file. I don't think it does anything if you don't specify a parameter, but I'm not certain on this.

-i | -i-

This is the interactive option. If you specify -i- then SSARC will run non-interactively, choosing sensible default options, such as -d-. -i is the default and will prompt you for the -d flag and the admin password. One caveat, even if you specify -i, you will be prompted for a response if the archive file already exists (and thus would be overwritten by the archiving process).

-y,

This option allows you to specify the user name and password. It has to be the admin account, so you will probably want -yadmin,topsecret, for password "topsecret". If there is a space in the password, then you would need to enclose the whole thing in quote marks: "-yadmin,super secret password". If this is not supplied then you will be prompted interactively for the password.

-x

This option allows you to archive only deleted files and projects. The default is -x-, which does not delete them. This is probably most sensibly used with the -d option, in other words, archive only deleted files, and then actually delete them from the Sourcesafe database.

Any file name can be specified here. If you want to specify a path that includes a space, then enclose the file name in quotation marks. The standard extension for Sourcesafe archive files is .ssa, so this should be used, although is not mandatory. The usual rules apply, if no path is specified, the file is created in the current directory. If this file always exists, SSARC will ask you whether or not you want to overwrite it.

List the Sourcesafe project(s) for archiving here. For one project, this could be "$/Project A". For the entire database, use $/. If you want to specify more than one project, separate them with spaces. If a project name has a space, enclose it in quote marks.

Examples

SSARC -d- -yadmin,password archive.ssa $/

Backup the entire default Sourcesafe database to archive.ssa, leaving the database exactly as it is.

SSARC -d- "-vlProduction Release" -yadmin,password -olog.txt archive.ssa $/Test

Backup everything since the version labelled 'Production Release' and create a log file with the results of the archiving process.

SSARC -d -x -yadmin,password archive.ssa "$/Project Global Domination" $/OtherProject

Archive, and delete the deleted files from two projects.

SSARC -i -yadmin,password -olog.txt "-cArchive Everything" archive.ssa $/

Archive the entire Sourcesafe database, while creating a log file, adding a comment, and running non-interactively, suitable for a scheduled task.

SSRESTOR

Summary

SSRESTOR is used for restoring previously-archived Microsoft Visual Sourcesafe projects. Several of the arguments for SSRESTOR do the same thing as they do in SSARC. The official syntax is:

SSRESTOR [-p -l -t -s -o -i- -y -x -c]

-p

This option specifies the project to restore to. If you do not specify the option, you will restore the project to its original location. To call it something new, try something like "-p$/New Project". This will not work if you already have the project in your Sourcesafe database -- you will get an error message: "$/Foo still exists in the database and cannot be restored to a different name".

-l[A]

The -l option by itself lists the meta-data from the archive file, and the name of the project or projects that were archived. Using -la lists every file in the archive. No restoring occurs here, it is purely for information purposes.

-t

This option lets you verify the contents of the archive file. If the file is a valid archive, you will get a message such as "Loading file list... done" and then "Checking archive file consistency.... done". Otherwise, if the file is not valid archive file you will apparently get one of two error messages: "CRC mismatch for ''" or "Incompatible archive file version -18399."

-s,

This is the same option as for SSARC. Check for more details. This lets you specify the locations of the Sourcsafe database (.ini file) and the data (normally the "data" subfolder).

-o

Paginate or redirect output. Same as for SSARC. Specify a log file with -olog.txt and the results of the command will be written there.

-i-

This option allows you to run SSRESTOR interactively or non-interactively. -i- will not prompt you for any information during the run, and choose sensible default values for the other options if they are not specified.

-y

Same as SSARC, you can specify login information, such as with -yadmin,password.

-x | -x-

This option lets you control whether or not you are restoring deleted items or not. -x lets you restore a deleted version of the project, which is probably not what you want. -x- is equivalent to the default (not specifying an option) and will restore the latest, non-deleted project. This is useful if you had a previously-deleted version of the project that you need to restore. Care should be taken with this option, since you will end up overwriting the latest version of the project.

-c

Same as SSARC, this allows you to add a comment for the operation, such as "-cRestored Archive".

This is the file name of the archive that you want to restore.

Same as SSARC, you can specify one or more projects to restore by separating them with spaces. Don't forget to enclose projects whose names have a space in quotes.

Examples

SSRESTOR -la -yadmin,password archive.ssa $/

Display a list of all of the files archived in archive.ssa.

SSRESTOR "-p$/Test 2" -sD:\newfolder\ -yadmin,password backup.ssa $/Test

Restores project $/Test to the database to a new location, $/Test 2, from the archive file backup.ssa, in a different Sourcesafe database.

Miscellaneous tips

• Putting the path to the \win32 folder in your PATH environment variable makes shell commands a lot easier
• If you get a message "Only ADMIN can run this utility", it means that you are either not specifying the admin account, or the password is incorrect. Use "-yadmin,password" if the admin password is "password", or "-yadmin," if the admin password is not set (not recommended!).
• If you are using an option that has a space in the argument, enclose the whole thing with quote marks, i.e. "-p$/Project A"
• A daily archive is easy to do with a Windows shell script, maybe something like this. Then use Scheduled Tasks to have this run every day.

  function q (str)
  	' to make the command a bit more readable, I hope
  	q = """" & str & """"
  end function
  
  PROJECT = "$/" 
  USERID = "admin"
  PASSWORD = "admin" 
  
  ' location of SSARC program
  SSARCPATH = "C:\program files\microsoft visual studio\common\vss\win32\ssarc.exe" 
  ' folder of srcsafe.ini
  SRCSAFEINIPATH = "" 
  ' prepended to filename in case you're doing more than one.
  LABEL = "ARCHIVE"
  ' destination of archive files
  BACKUPFOLDER = "C:\BACKUPS\"  
  
  ' generate a name based on the time.
  today = now()
  backupfilename = LABEL & "-" & formatdatetime(now,2) & ".ssa"
  
  cmd = q(SSARCPATH) & " " & _
  	q("-s" & SRCSAFEINIPATH & ",") & " -i- " & " -d- " & _
  	q("-y" & USERID & "," & PASSWORD) & " " & _
  	q(BACKUPFOLDER & backupfilename) & " " & q(PROJECT)
  
  Set WshShell = WScript.CreateObject("WScript.Shell")
  wscript.echo cmd
  WshShell.run cmd
  set wsshell = nothing
  

Other Information

There is very little in the way of good documentation on this utilities, which is why I wrote this document. Here are links to the MSDN documentation on and .

Last updated: November 11, 2004

附应用一例：

============================================================

@echo off
@title Backing up SourceSafe databases
set SsPath=C:\vss\win32\
set BakPath=F:\VSSBackup\content\

FOR /F "tokens=2-2" %%i IN ('date /t') DO SET DAY=%%i

del /F /Q "%BakPath%Backup-IRISoutput.txt"
del /F /Q "%BakPath%Backup-IRISDatabase.ssa"
del /F /Q "%BakPath%Backup-Themisoutput.txt"
del /F /Q "%BakPath%Backup-ThemisDatabase.ssa"
del /F /Q "%BakPath%Backup-COPCoutput.txt"
del /F /Q "%BakPath%Backup-COPCDatabase.ssa"
del /F /Q "%BakPath%Backup-GHDoutput.txt"
del /F /Q "%BakPath%Backup-GHDDatabase.ssa"

"%SsPath%ssarc.exe" -d- -s"D:\IrisVSS" -i- -yadmin,dladmin -o@"%BakPath%Backup-IRISoutput.txt" "%BakPath%Backup-IRISDatabase.ssa" $/
echo  iris Finished backups

"%SsPath%ssarc.exe" -d- -s"D:\Themis" -i- -yadmin,dladmin -o@"%BakPath%Backup-Themisoutput.txt" "%BakPath%Backup-ThemisDatabase.ssa" $/
echo  themis Finished backups

"%SsPath%ssarc.exe" -d- -s"D:\COPC" -i- -yadmin,dalian -o@"%BakPath%Backup-COPCoutput.txt" "%BakPath%Backup-COPCDatabase.ssa" $/
echo  copc Finished backups


"%SsPath%ssarc.exe" -d- -s"D:\GhdVSS" -i- -yadmin,dladmin -o@"%BakPath%Backup-GHDoutput.txt" "%BakPath%Backup-GHDDatabase.ssa" $/
echo  GHD Finished backups


@echo on

============================================================