Robocopy is a 32-bitcommand-line tool used for file replication. This tool helps maintain identicalcopies of a directory structure on a single computer or in separate networklocations. Robocopy is included in theMicrosoft® Windows® Resource Kit.

Robocopy version XP010 requires Microsoft® Windows® Server 2003,Microsoft® Windows® XP, Microsoft®Windows® 2000, or Microsoft® Windows NT® version 4.0.

Using Robocopy, you cancopy a single directory, or you can recursively copy a directory and itssubdirectories. The tool classifies files by whether they exist in the sourcedirectory, in the destination directory, or in both. In the latter case, thetool further classifies files by comparing time stamps and file sizes betweenthe source file and the corresponding destination file. You control whichclasses of files are copied.

If a file exists in boththe source and destination locations, by default Robocopy copies the file onlyif the two versions have different time stamps or different sizes. This savestime if the source and destination are connected by a slow network link. Youcan also specify that copies are restarted in the event of a failure, whichsaves even more time when your network links are unreliable.

Robocopy allows you to dothe following:

·    Usefile names, wildcard characters, paths, or file attributes to include orexclude source files as candidates for copying.

·    Excludedirectories by name or by path.

·    Deletesource files and directories after copying (that is, move rather than copythem).

·    Deletedestination files and directories that no longer exist in the source.

·    Controlthe number of times the program retries an operation after encountering arecoverable network error.

·    Schedulecopy jobs to run automatically.

·    Specifywhen copying is to be performed.

·    Monitora directory tree for changes.

·    Selectivelycopy file data.

New Features in Robocopy VersionXP010

Robocopy version XP010 includes a number ofenhancements. For example, you can now do the following:

·    CopyJunctions – Volume Mount Points and Directory Links. By default these arecopied as normal directories, as it may not be possible to create an equivalentJunction in the destination, especially if the source and destination reside ondifferent machines. Copying a tree that contains a Volume Mount Point canresult in unexpectedly large volumes of data being copied.

Use/XJ if you would prefer Robocopy toskip Junctions.

·    Acton and modify more file attributes.

In addition to supportfor the R, A, S, and H attributes:

/XA and/IA now also accept and select on the following addition fileattributes:

C – Compressed files

N – files Not contentindexed

E – Encrypted files

T – Temporary files

O – Offline files

/A+ and/A- now also accept and modify the following additional attributetype:

N – files Not contentindexed

T – Temporary files

·    Selectfiles based on their Last Accessed Dates.

/MAXLAD:n excludes files with a LastAccess Date older than n.

/MINLAD:n excludes files with a LastAccess Date newer than n.

If n < 1900, n istaken to be a time span in days.

If n >= 1900, nmust be a date in the form YYYYMMDD

·    Copya new class of file : “Tweaked” files.

Use/IT to include and process Tweakedfiles.

A Tweaked file isdefined to be one that exists in both the source and destination,

with identical sizeand timestamp, but different attribute settings.

Form more informationsee “Robocopy File Classes” later in this document.

·    Copyvery long path names (longer that 256 characters).

Previousversions of Robocopy would fail to copy any pathname longer than 256characters. The program has now been enhanced to handle pathnames of anylength, up to the internal Windows limit of nearlt 32,000 characters.

·    Getbetter information on data volumes for large copies.

Previousversions of Robocopy used 32-bit counters which would overflow when more than 2gigabytes of data was processed, resulting in incorrect output in the runsummary. This version now uses 64-bit counters to avoid this problem.

·    Moreeasily correlate Robocopy errors to network errors.

Robocopynow displays the date and time that errors occur to assist in tracking downcommunication problems.

·    Recovermore quickly and robustly from file copy failures.

Thisversion of Robocopy now timestamps destination files with a January 1980 dateduring copies. Thus, if a copy of a newer file is interrupted and re-run, thedestination file will seem to be older than the source file and be copiedcorrectly.

·    Copyfiles in Backup Mode.

Use the/Bswitch to copy all files in Backup Mode. Use the/ZB switch to try to copy files in Restartable Mode (for greaterresiliency), and automatically switch to Backup Mode if the Restartable copyfails with an “Access Denied” error.

You must have the Backup Files and Restore Filesprivileges to copy files in Backup Mode using/B or/ZB.

Backup mode copies are not restartable, but theyenable you to copy some files as a Backup Operator that you would not be ableto copy as a normal user.

·    Create,Edit, View, and take parameters from Robocopy Job (.RCJ) Files.

Use the/SAVE:jobswitch to save parameters to a Job file.

Use the/JOB:job switch to take parameters fromone or more Job files.

Use the /JOB:joband/SAVE:job switches together to edit a Job file.

Use the/QUIT switch to end execution afterprocessing command line arguments.

Use the/JOB:job and/QUIT switches together to view the contents of a job file.

Use the/NOSD to create a Job template with noSource Directory.

Use the/NODD to create a Job template with noDestination Directory.

Robocopy Job (.RCJ)files are simple text files that can also be edited manually.

For more information,see “Job Files” later in this document.

·    Monitorthe source directory tree for changes, and copy changes when they occur.

Usethe/MON:n switch to specify the minimum number of changes that mustoccur before running again.

Usethe/MOT:m switch to specify the minimumtime, in minutes, that must elapse before running again.

If youonly specify one of these switches, the other is assumed to have a value of 1.

WhenMonitoring is specified, Robocopy never terminates. Instead, it enters a loopthat performs a normal Robocopy pass and then monitors the source directorytree for changes, until bothn changes have been detected andmminutes have elapsed.

Thiswhole process of copying and monitoring is repeated, ad infinitum, until theuser manually terminates the Robocopy process.

For more information,see “Monitoring a Directory Tree” laterin this document.

·    Controlbandwidth usage.

Use/RH:hhmm-hhmm to specify Robocopy runhours.

When Run Hours have been specified, Robocopy willonly start new copies when the local system time is between the two specifiedtimes.

Use the/PFswitch to tell Robocopy to check its run hours on a Per File basis.

By default Robocopy will check its run hours on aper pass basis.

Use the/IPG:nswitch to specify an Inter-Packet Gap of n milliseconds.

Robocopy will then sleep for the given time intervalbetween each 64k chunk of file data transferred. This can be used to free upsome bandwidth on slow links.

For more information,see “Controlling Bandwidth Usage” later in this document.

·    Exercisemore granular control over what is copied,

·    CopyNTFS File Ownership Information, and

·    CopyNTFS File Auditing Information.

Use the/COPY:[D][A][T][S][O][U] switch to specifyexactly what to copy.

The flags listed copy fileData,Attributes,Timestamps, NTFSSecurity (ACLs), NTFSOwnership information, and NTFSaUditing information,respectively.

Some previous versions of Robocopy were able tocopy NTFS ACLs. This version adds the ability to copy NTFS Ownership andAuditing information as well.

Use the/COPYALLswitch to copy everything (equivalent to/COPY:DATSOU).

Use the/NOCOPYswitch to copy nothing (this can be useful with/PURGE).

The default is/COPY:DAT, or/COPY:DATSif/SECis specified.

If file Data is copied, then file Timestamps arealso copied.

The/TIMFIXor/SECFIX switches are no longersupported. If you have scripts that use these switches you must edit them touse/COPY:instead./COPY:Treplaces the old/TIMFIX, and/COPY:Sreplaces the old/SECFIX.

You must have the Manage Audit Logs privilege tocopy file auditing information using/COPYALLor/COPY:U. 

·    Controlwhat is written to the output log.

Usethe/TS (Time Stamps) switch toinclude source file timestamps in the output.

Usethe/FP (Full Paths) switch toinclude full file pathnames in the output.

Usethe/NC (No Classes) switch toremove Robocopy file classes from the output.

Usethe/NS (No Sizes) switch to removefile and directory sizes from the output.

Use the/NFL(No File List) switch to suppress logging of file names.

Use the/NDL(No Directory List) switch to suppress logging of directory names.

Use the /NJH(No Job Header) switch to suppress output of the job header.

Use the /NJS(No Job Summary) switch to suppress output of the job summary.

File copy failures will still be logged even if/NFL is used.

If/NDLis used on its own, log files will contain fewer lines, but may use more diskspace, as full pathnames of files will be logged instead of simple names.

·    Logoutput to both the console window and a log file on disk, simultaneously.

Use/TEE to request simultaneous output to boththe screen and also a log file specified by/LOG or/LOG+. Thisenables you visually monitor progress in a small console window on screen,while the full log is also written to disk.

Command-line Reference

To run Robocopy, use the following syntaxat the command prompt:

ROBOCOPYsource destination [file [file]...] [options]

The following table defines these syntaxelements.

To view brief usage instructions at the commandprompt, runROBOCOPY withoutspecifying any command-line options.

The following table defines the command-lineoptions that you can use with Robocopy.

Usage Notes

Thefollowing sections provide more details about using the command-line options totailor Robocopy to match your needs.

BackwardsCompatibility

This version of Robocopy was developed and tested under MicrosoftWindows XP.

The recommended minimum operating system platform for this versionof Robocopy is therefore Microsoft Windows XP, or Microsoft Windows Server2003.

Robocopy uses only standard, publicly documented Win32 APIsthroughout. For example, the program uses CopyFileEx() to copy files, andFindFirstFile() and FindNextFile() to read directories. In theory, Robocopyshould run on any operating system that supports these APIs, such as Windows NTversion 4.0 and Windows 2000.

However if you choose to run this version of Robocopy on Windows NTversion 4.0 or Windows 2000, please be aware that only limited testing wasperformed on these platforms, and Robocopy’s theoretical performance may differfrom practical results.

AsRobocopy uses the CopyFileEx() Win32 API,it can not run on Windows NT 3.1, Windows NT 3.5x, nor Windows 95, Windows 98 or Windows ME.

Using Robocopy Within a UNIXShell

You can specify all Robocopy switches inUNIX style (for example,-ETA instead of/ETA). You canalso specify source and destination directory paths using the UNIX delimiter(/), rather than the native Windows delimiter (\).

The only restriction is that any argumentthat begins with a UNIX slash mark (/) is treated as a switch if the argumentcontains only a single slash mark (/). In other words, /dir is treated as a switch; but //server/share/dir and /download/test aretreated as paths.

This avoids any possible confusion betweenswitches and single-level paths subordinate to the root of a drive. To specifya directory as an argument, you must use an alternate expression for its path,such asX:/dir or//server/C$/dir.

Processing a Directory Tree

Bydefault, Robocopy processes only the single source directory specified on thecommand line. To process the entire directory tree, including subdirectories,use/S or/E. To limit the copy to only the topn levels of the source directory tree, use/LEV:n.

Forexample /LEV:2 will cause Robocopy to process the top two directory levelsonly, i.e. just the root directory of the source and any directory directlyunder the root. Subdirectories of directories under the root will not beskipped.

Bydefault Robocopy will handle file and directory path names up to almost 32,000characters in length. If for any reason you wish to disable this support forvery long path names, use the/256switch. This causes Robocopy to revert to normal path name semantics, and amaximum path name length of 256 characters.

Ifthe/256 switch is used and Robocopyencounters a path name longer than 256 characters, one of the following errorsmay be reported, depending on the operation being performed on the very longpath name at the time :

The filename, directory name, or volume label syntax is incorrect.

The system cannot find the file specified.

The file name or extension is too long.

While walking a directorytree, Robocopy may encounter Junctions in the file system. These may be VolumeMount Points created using the MOUNTVOL command, or Directory Links createdusing the LINKD command. Robocopy handles Junctions in the source by creating anormal Directory of the same name in the destination, because it may not bepossible to replicate the Junction in the destination. This is often the caseif the source and destination are on different machines, as the target volumeor directory of the Junction may not exist on the destination machine. Notethat copying Junctions in this way can result in unexpectedly large volumes ofdata being copied if, for example, the source directory tree contains a VolumeMount Point. You can disable processing of Junctions by specifying the/XJswitch, which causes Robocopy toexclude Junctions from further processing. If/XJ is specified, Junctions are skipped.

RetryingAfter a Failed Copy

When a copy operation fails and returns anerror, Robocopy waits and then retries the operation until it succeeds or untilthe retry limit is reached. The defaults are a 30-second wait and up to 1million retries.

Changing Default Retry Parameters

Use the/W:n switch to change thewait time (in seconds) between retries, wheren is a positive decimalinteger, or zero (0) if you do not want any wait time between retries.Similarly, use the/R:n switch to change the retry limit.If an invalid value is given for/Wor/R, Robocopy uses the defaultvalue.

To change the default retry parameters, usethe/REGswitch on a valid Robocopy command that specifies non-default values for/W and/R. When/REG is used, the values you specify for/W and/R are stored in the registry and used as default values for/W and/R in future Robocopy runs where/W and/R arenot specified on the command line. Youcan always specify/W or/Rto override the stored settings.

Handling “Network Name Not Found” Errors

Robocopy does not automatically retry all failedoperations. Certain errors in some operations are not retried, where practicalexperience indicates that this would be futile. For example, the “Network NameNot Found” error usually indicates that a remote computer exists but does nothave a share with the given name. Because manual intervention is required tocreate a suitable share name on the remote computer, this error usually causesthe attempted operation to fail without a retry.

In some situations, however, this might notbe the desired action. For example, in a software publishing environment it iscommon to delete a share name, update the contents of the share, and thenrecreate the share name. In this scenario, you can use the/TBD switch to retry a copy operation when Robocopy encounters a “NetworkName Not Found” error.

Restarting from the Point of Failure

NormallyRobocopy will restart failed copies from the beginning of the file. You canoverride this default behaviour by specifying the/Z switch (or the/ZBswitch) which requests restartable copies - with/Z, failed copies will usually restart from close to the point offailure rather than the beginning of the file. See “Copying NTFS SecurityInformation” later in this document for more information on/ZB.

If you use/Z,/B, or/ZB, this can decrease Robocopy performance and throughputsignificantly, as these options involve extra overhead. These options aretherefore only recommended when experience indicates you really need them.

Specifying File and Directory Names

To specify a directory or file name or pathname that includes one or more spaces, you must enclose the entire file or pathname in quotation marks. For example:

ROBOCOPY “\\sales\reports\Fiscal 97” “C:\finance\Year End\sales” /XF “Budget96*.*”

Any file names that appear in the command linemust be specified as individual arguments separated from other arguments bywhite space, and not appended to the source or destination directory pathnames. If no such arguments appear in the command line, Robocopy defaults to allfiles.

By default, Robocopy treats all non-switchcommand-line arguments as file names, paths, or wildcard characters. Thesenames can be alternated with switch arguments, but the command line is easierto read when they are grouped together.

The command line is parsed from left toright. The meaning of any non-switch argument depends on where it appears withrespect to an/XF or/XD switch. Normally there must be twonon-switch arguments before any/XFor/XD switch, and these are treatedas the path names of the source and destination directories, respectively. Theonly exception is when/NOSD or/NODD is used as a directoryplaceholder to define a Template Job File. See “Robocopy Job Files” later inthis document for more details.

After the source and destination pathnames, and until Robocopy encounters an/XFor/XD switch, any non-switchargument is treated as either a file name or a wildcard character (but not apath) indicating one or more files to include as candidates for copying.

The/XFswitch specifies that all subsequent file names, paths, and wildcard charactersare files to exclude from copying until an/XDor /IF switch is found.

The/XDswitch specifies that all subsequent file names, paths, and wildcard charactersare directories to exclude from copying until an/XF or/IF switch isfound.

The/IF switch specifies that allsubsequent file names and wildcard characters are candidates for copying untilan/XD or/XF switch is found./IFis intended for use within Robocopy Job Files, but it can also be used on thecommand line.

The following table compares these subtledifferences in allowed values:

The following example shows the correct useof these switches:

ROBOCOPY c:\source d:\dest *.c* /XF *.cpp /S /XD binc:\source\unwanted

In this example, Robocopy recursivelycopies the directory tree (including subdirectories) with the root c:\source,excluding the subdirectories bin and c:\source\unwanted. All files whoseextensions begin with c are copied, except files with the extension .cpp.

Using Robocopy File Classes

For each directory processed, Robocopyconstructs a list of files in both the source and destination directories. Thislist matches the files specified on the command line for copying.

Robocopy then cross-references the lists,determining where files exist and comparing file times and sizes. The programplaces each selected file in one of the following classes.

By default, Changed, Newer, and Older filesare candidates for copying (subject to further filtering, as described later).Same files are not copied. Extra and Mismatched files and directories are onlyreported in the output log.

Normally, Tweaked files are neither identifiednor copied – they are usually identified as Same files by default. Only when/IT is used will the distinction between Same and Tweaked files be made, andonly then will Tweaked files be copied.

 Usethe following switches to override this default behavior.

You do not need to specify any of these argumentsto include the current version of source files in the destination tree. In mostsituations, Robocopy includes these files by default.

The/XLswitch limits Robocopy to copying a file from the source directory treeonly when a corresponding file of the same name already exists in thedestination. This provides a convenient mechanism for maintaining a copy of aselected subset of the source tree. Using the/IS switch alone, with no other switches, forces a total refresh ofthe destination tree. Using the /IT switch provides a way to copy some Samefiles but not others by changing the attributes of those you wish to be copiedin either the source or the destination.

During a copy operation Robocopy places aJanuary 1980 time stamp on the destination file, and updates this to the sourcefile’s time stamp only when the copy is complete. If you quit Robocopy during acopy operation, any incompletely copied destination file will therefore have anearlier time stamp than its corresponding source file. If you restart the samecopy operation, Robocopy treats this file as an Newerfile and will therefore complete the interrupted copy, unless youhave specified /XN.

The most appropriate use for/XOis to synchronize two directorytrees so that they can be updated simultaneously in separate areas. To ensurethat the latest files are present in both directory trees, copy with/XO first in one direction and then inthe other.

You can use switches to exclude files basedon their size or time stamp./MAX:nexcludes files larger thann bytes,and/MIN:n excludes files smaller thann bytes. Similarly,/MAXAGE:n excludes files with a lastmodified date older thann and/MINAGE:n excludes fileswith a last modified date newer thann, wheren is either a time spanin days (ifn < 1900), or a date in the form YYYYMMDD (ifn>= 1900).

Similarly,/MAXLAD:n excludes fileswith a Last Accessed Date older thann and/MINLAD:n excludes fileswith a Last Accessed Date newer thann, wheren is either a time spanin days (ifn < 1900), or a date in the form YYYYMMDD (ifn>= 1900).

Using Precise File Times and Long FileNames

Although it is preferable to have both thesource and destination directories reside on NTFS partitions, you can useRobocopy to copy to other file systems, such as HPFS or FAT. If you do so,however, file times might be inaccurate due to rounding errors, and long filenames might not be preserved.

Handling FAT File Times on NTFS Drives

File-time granularity is 100 nanoseconds onNTFS, and two seconds on FAT, so copying a file from NTFS to FAT causes filetimes to be rounded to a value that the FAT file system can manage. When boththe source and destination volumes rea NTFS, file times are compared exactly.When either the source or destination volume is not an NTFS volume, Robocopyconsiders file times to be identical if they are within two seconds of eachother. Without this two-second margin, the program might classify manyotherwise unmodified files as Older or Newer files, which would result inunnecessary copying of unchanged files. Sometimes you need to override thishandling of file times. Suppose you copy an NTFS tree to a FAT volume, and thencopy the FAT tree (with its rounded file times) to a local NTFS drive. Later,when you want to recreate the original tree exactly, you do not want to refreshthe entire tree.

In this scenario, you can use the/IS and/COPY:T switchestogether to copy just file times independently of file data for Same files,rather than copying the files themselves again. See “Selectively Copying FileData” later in this document for more information on/COPY.

Some third-party operating systems declarethat their volumes are NTFS, but only implement FAT-style file times with a2-second granularity. When copying to such a destination from a true NTFSvolume, file time rounding may occur, along with unnecessary copying of filedata in subsequent jobs. If you encounter this situation, you can use the /FFT (FAT File Times) switch to tellRobocopy to consider file times to be identical if they are within 2 seconds ofeach other, even though both source and destination appear to be NTFS. Thiseliminates unnecessary copying in this scenario.

Handling Long File Names on FAT or HPFS Volumes

When the destination is on a FAT or HPFSvolume, you might experience problems copying files and directories with longnames or with names that include extended Unicode characters. To overcome theseproblems, use the/FAT switch. Thisswitch prompts Robocopy to create destination files with system-generated namesin the standard 8.3 FAT file system format.

Working with File Attributes

By default, Robocopy ignores most sourcefile attributes (read-only, archive, system, and hidden) when selecting filesto copy. Any file matching other specified conditions is copied regardless ofits attribute settings. You can use command-line switches to modify thisdefault behavior, as described in the following sections.

Including or Excluding Files Based on Specified Attributes

The/IA:{R|A|S|H|C|N|E|T|O}switch includes only files with one or more of the specified attributes set.Files that do not have any of the specified attributes set are excluded fromfurther processing and are not copied.

/IA can be useful in data staging applications. For example, you canspecify/IA:R to copy only read-onlyfiles from a test Web server to a live Web server. Developers can remove theread-only attribute from files on the test server while they edit and test thefiles. Until the read-only attribute is turned on again, these files are notreplicated on the live server.

Another switch,/XA:{R|A|S|H|C|N|E|T|O}, can be used to exclude files if one ormore of the specified attributes is set. For example, you can specify/XA:R to prevent read-only files frombeing copied. Similarly,/XA:SHexcludes files with either the system or hidden attribute set.

Any combination of the following fileattribute types can be used with/IAand/XA:

R   –    Read only files

A   –    Archive files

S    –    System files

H   –    Hidden files

C   –    Compressed files

N   –    files Not contentindexed

E   –    Encrypted files

T   –    Temporary files

O   –    Offline files

Robocopy processes/IA before/XA when bothswitches are specified in the same Robocopy command.

The/Aand/M switches allow only thosesource files with the archive attribute set to be selected for copying. Aftercopying, the archive attribute of the source file is either left set (if/A was used) or turned off (if/M was used).

Temporary files are normally deleted by theowning application when it is no longer needed. When present on the system theyare usually in use, and therefore copy delays or failures will often occur ifyou try to copy them.

Offline files have been physically removed tooffline storage, and severe delays may be encountered in copying them, whilethe system retrieves them.

Changing File Attributes After Copying

After a file has been successfully copiedto the destination, the attributes of the destination file are set by default tomatch those of the source file. To modify this default behavior, you can usetwo other switches:

/A+:{R|A|S|H|N|T} sets attributes, and

/A-:{R|A|S|H|N|T}  resets or turns off attributes.

For example,/A+:A turns on the archive attribute in destination files (to makeit easier to back them up)./A-:RSH removes the read-only, system, and hiddenattributes from destination files (to make it possible to see and edit them).

The order of attribute operations on newlycopied destination files is as follows:

    1.   Attributes are copied to the destination filefrom the source file.

    2.   Attributes specified by/A+ are set (turned on).

    3.   Attributes specified by/A- are reset (turned off).

Any combination of the following fileattribute types can be used with/A+and/A-:

R   –    Read only files

A   –    Archive files

S    –    System files

H   –    Hidden files

N   –    files Not contentindexed

T   –    Temporary files

Maintaining True Replication

Ifyou require the destination directory tree to be maintained as anexact mirror of the source directorytree, you must delete files and directories from the destination whenever theydisappear from the source. To accomplish this, use the/E and/PURGE switchesin combination, or use the/MIRswitch

The /PURGE switch causes Robocopy todelete all Extra and Mismatched destination files and directories. After aMismatched destination entry has been deleted, the corresponding source entryis then treated as a Lonely file or directory and processed accordingly. When /PURGE results in the deletion of an Extraor Mismatched destination directory, the entire directory tree, including allsubordinate files and subdirectories, is deleted (even if/S or/E is notspecified).

Use /PURGE and/MIR very carefully. If you inadvertently specify/PURGE or/MIR with an existing destination directory, Robocopy can quicklydelete a large amount of data from the destination.

Toprevent specific directory trees or files from being deleted when you use/PURGE, you must exclude them by name,using the/XD or/XF options./XD and/XF excludefiles and directories before all other processing.

Becausethe/XX switch excludes Extra filesfrom further processing, the/PURGEswitch has no effect when/XX isalso used.

SelectivelyCopyingFileData

Once a file has been selected for copying,you can choose precisely which data associated with the file is copied usingthe/COPY:copyflagscommand line argument,wherecopyflags can be any combination of the following :

·        D     to copy file Data

·        A     to copy file Attributes

·        T     to copy file Timestamps

·        S     tocopy NTFS Security information (ACLs)

·        O    tocopy NTFS Ownership information

·        U    tocopy NTFS aUditing information

For ease of use the following alternativeswitches are also provided :

·        /COPYALL    copies everything (equivalent to/COPY:DATSOU).

·        /NOCOPYcopiesnothing (which can be useful if/PURGEis also used).

·        /SEC                copiesdata, attributes, and NTFS ACLs (like/COPY:DATS).

Any combination of these flags can be used,if you have the appropriate access rights. However, if file data is copied,file timestamps are also copied. By default Robocopy assumes/COPY:DAT,and will copy file data, attributes, and timestamps.

You musthave the Manage Audit Logs privilege to copy file auditing information using/COPYALL or/COPY:U. 

Torefresh security information for existing destination files and directorieswithout copying file data, use the/ISswitch together with the/COPY switch without theD flag. For example/IS/COPY:SOUwould refresh all security information for all selected files, withoutcopying any file data.

Torefresh time stamps on existing destination files and directories withoutcopying file data, use the/ISswitch together with the/COPY switch without theD flag. For example/IS/COPY:Twould refresh all security information for all selected files, withoutcopying any file data.

Copying NTFSSecurity Information

Ifboth the source and destination directories reside on NTFS volumes, you can useRobocopy to copy NTFS security information. The most common requirement is topreserve NTFS ACLs during a copy. To do this, use the/SEC switch tocopy NTFS file permissions when you copy files to a destination for the firsttime. If you also need to preserve NTFS ownership and auditing information youshould use/COPYALL.

If eitherthe source or the destination volume is not NTFS, requests to copy securityinformation are ignored. Only one attempt is made to copy NTFS securityinformation for each file or directory copied.

Torefresh security information for existing destination files and directorieswithout copying file data, use the/ISswitch together with the/COPY switch without theD flag. For example/IS/COPY:SOUwould refresh all security information for all selected files, withoutcopying any file data. See “Selectively Copying File Data” earlier in thisdocument for more information on/COPY.

Whenyou copy security information, you might notice a short delay after Robocopyprints its banner and before it displays arguments on the screen. This delayoccurs because the program is checking for the NTFS file system at both ends.Copying NTFS file security information fails if you have insufficient accessprivileges at either the source or the destination.

Formore information about access privileges, see “Scheduling Robocopy Jobs” laterin this document.

Youcan copy security information between computers in separate domains even ifthey do not have trust relationships. However, this applies securityinformation that is unknown to the destination computer to the destination directorytree. When you view this information on the destination, user accounts areshown as “Account Unknown.” If you copy these permissions back to a computer inthe originating domain, they are interpreted correctly again.

Ifyou copy NTFS security information (ACLs) along with file data, it is possibleto copy files to which you have read access, but not write access. After such afile is copied once, and the ACLs are applied, you may find that to get an“Access Denied” error when you try to copy the file again.

Inthis situation you should use the/Bor/ZB switch to copy the files inBackup Mode.

/B copies all files with backup semantics (Backup Mode)./ZB first attempts to copy files inrestartable mode (for greater resiliency) but if that fails with an “AccessDenied” error it automatically retries the copy using Backup Mode.

You musthave the Backup Files and Restore Files privileges to copy files in Backup Modeusing/B or/ZB.

Backupmode copies are not restartable, but they enable you to copy some files as aBackup Operator that you would not be able to copy as a normal user.

If youuse/Z,/B, or/ZB, this candecrease Robocopy performance and throughput significantly, as these optionsinvolve extra overhead. These options are therefore only recommended whenexperience indicates you really need them.

MovingFiles

In some situations, you may want to movefiles instead of copying them, especially if disk space is at a premium on yournetwork. You can use the/MOVE switch to delete source files from thesource directory tree after they have been successfully copied to thedestination./MOVEalso deletes empty directories from the source directory tree.

Even with/MOVE specified,however, Robocopy deletes only those source files that it successfully copiesto the destination. There is no guarantee that a skipped source file isidentical to its corresponding destination file (even if the file times andsizes are identical) until immediately following a successful copy. For that reason,some files and directories (such as skipped Same files) might remain in thesource tree even when/MOVE is specified. You must determine whetherto delete the remaining entries, and do so manually.

To move files but still preserve the source directorytree structure, use/MOV instead of/MOVE.

Minimizing Directory Fragmentation

When you copy a directory tree for thefirst time, the files contained in each directory are copied into it as it iscreated. The directory entry for each file is created first, and then the filedata is copied.

If the tree contains large directories,however, this sequence can cause fragmentation of the directory structure. Whendisk allocation for the directory itself is expanded, the new directory extentcan be separated from the rest of the directory by large amounts of file data,which can reduce later file system performance significantly.

Use the/CREATE switch to minimize directory fragmentation when you copy alarge tree for the first time. When/CREATEis specified, Robocopy creates only the directory tree and zero-length files asplaceholders for the actual files. No file data is copied. Immediatelyfollowing a Robocopy command containing/CREATE,run the same command again without/CREATEto copy the file data to the destination.

Robocopy does not use/CREATE by default, because pre-creating a directory tree and thencopying file data takes more time than just copying the files. For  directory trees

When using this technique, do not use/XO, because the zero-length filescreated by the initial/CREATEcommand are tagged as “Older” files on the second run.

Robocopy Job Files

Given the largenumber of command-line options available, it is easy to create Robocopycommands that are extremely long, and unwieldy to manipulate. Using RobocopyJob Files can greatly simplify matters.

Robocopy JobFiles are simple text files containing one Robocopy parameter per line, thatyou can create, view, and edit manually using a text editor, or, more simply,you can use Robocopy itself for all of these tasks.

There are threebasic switches that are used in Robocopy Job File processing. The/SAVE:jobswitch tells Robocopy to save its current set of parameters to the named file,the/JOB:job switch tells Robocopy to readparameters from the named file, and the/QUITswitch tells Robocopy to terminate after processing the command line.

Both /SAVEand /JOBexpect the file to have a .RCJ suffix, and append a .RCJ suffix to the providedfilename if it does not have one.

For example,you may use a Robocopy command to back up source files as follows  :

ROBOCOPY C:\SRC D:\SRC/E *.C* *.H*

To encapsulatethis command in a Robocopy Job File, you could do the following :

ROBOCOPY C:\SRC D:\SRC/E *.C* *.H* /SAVE:SBACKUP

This creates aRobocopy Job File named SBACKUP.RCJin the current directory that encapsulates all the Robocopy parameters youspecified prior to the /SAVE switch.

/SAVEis actioned as soon as it is encountered on the command line. Any arguments onthe command line after /SAVE willnot be saved.

/SAVEwrites to the specified file immediately, with no warning if the target filealready exists. Care should be taken that you do not overwrite existing fileswhen using /SAVE to create a newRobocopy Job File.

To run theresulting Robocopy Job File at a later date, assuming the same workingdirectory, the following command would suffice :

ROBOCOPY /JOB:SBACKUP

Actually, thecommand given above to create a Robocopy Job File might not be ideal, as afterprocessing the /SAVE switch andcreating the Robocopy Job File, Robocopy would continue on and run with thegiven parameters.

To just createthe Robocopy Job File without running the job, you can use the/QUIT switch as follows :

ROBOCOPY C:\SRC D:\SRC/E *.C* *.H* /SAVE:SBACKUP /QUIT

To view theverbatim contents of the generated .RCJ file you can either load it into a texteditor (e.g. by running NOTEPAD SBACKUP.RCJ)or display its contents in the console window (e.g. by running TYPE SBACKUP.RCJ).

Alternatively,you can get a more succinct idea of its contents by running :

ROBOCOPY /JOB:SBACKUP /QUIT

This causesRobocopy to load the file, display its parameters, and then quit.

To edit a jobfile, you can use /JOB/SAVE and /QUIT together asfollows :

ROBOCOPY /JOB:SBACKUP /XF *.HLP /SAVE:SBACKUP /QUIT

This loads thenamed job, adds parameters to exclude .HLP files from the job, and updates iton disk.

Alternatively,you can edit job files using a text editor. The format of Robocopy Job Files isstraightforward. They contain one Robocopy parameter per line (parameterscontaining colons, e.g. /LOG:logfileor /MAX:n,count as one parameter and must be specified on a single line, with no spacesaround the colon). Leading white space is ignored, as is any text after twoconsecutive colons, which is considered to be a comment. View aRobocopy-generated .RCJ file to examine the format in more detail.

MultipleRobocopy Job Files can be specified on the Robocopy command line. For example,you might have a large list of files to be excluded from copying. You could usean editor to create a text file containing this exclusion list as follows :

      /XF

     file1

     file2

     file3

     ...

Once this issaved with a .RCJ suffix, e.g. EXCLUDE.RCJ,it can be used in conjunction with other Robocopy Job Files, for example asfollows :

      ROBOCOPY /JOB:SBACKUP/JOB:EXCLUDE

When multiple job files are used, their contentsare cumulative. For example if a job specifies /XA:R and is used in conjunction with another that specifies /XA:SH then the result will be /XA:RSH.This also means that you must make sure that only one source directory and onlyone destination directory is specified in any set of job files that are usedtogether.

It is sometimesuseful to create Robocopy Job Files that can be used as templates for similartypes of copies, and for this purpose it is perfectly valid to save a job filewithout specifying a source directory or destination directory or both. Such ajob file cannot be run on its own, of course, unless the source and destinationdirectories are specified at run time.

For example:

      ROBOCOPY *.c* *.h* /SAVE:SBACKUP /QUIT

Could be usedcreate a template job SBACKUP.RCJfor backing up source files.

To use thistemplate to back up different projects you might later run:

      ROBOCOPY /JOB:SBACKUPC:\PROJECTS\PROG1 D:\PROJECTS\PROG1

      ROBOCOPY /JOB:SBACKUPC:\PROJECTS\PROG2 D:\PROJECTS\PROG2

However, if thelist of files you wish to include contains a specific file name (as opposed towild cards like *.c*), such asMAKEFILE, then this approach will fail. You mightattempt to create such a template job as follows:

      ROBOCOPY *.c* *.h* MAKEFILE /SAVE:SBACKUP/QUIT

The problemhere is that Robocopy assumes that the first three non-switch, non-wild cardarguments are the source pathname, the destination pathname, and the first of alist of files to include, repectively, and therefore will assume that MAKEFILE is the source directory, rather than afilename to include.

To handle thissituation you can use the/NOSD and/NODD switches in place of the sourceand destination directories respectively. In the example above you should usethe/NOSD switch to declare that noSource Directory is being specified, and the/NODD switch to declare that no Destination Directory is beingspecified, as follows:

      ROBOCOPY /NOSD /NODD *.c* *.h* MAKEFILE/SAVE:SBACKUP /QUIT

Obviously, botha source directory and a destination directory must be specified, so/NOSD and/NODD are only useful in the creation of template job files.However, template job files can be a powerful tool, as multiple job files canbe specified on a single Robocopy command line.

Extending theexample of backing up source files further, you could create a template jobapecifying file section options, then further jobs for specific source codeprojects:

      ROBOCOPY /NOSD /NODD *.c* *.h*MAKEFILE      /SAVE:SB /QUIT

      ROBOCOPY C:\PROJECTS\PROG1 D:\PROJECTS\PROG1/SAVE:P1 /QUIT

      ROBOCOPY C:\PROJECTS\PROG2 D:\PROJECTS\PROG2/SAVE:P2 /QUIT

   Etc…

Such a jobstructure would enable you to back up your projects simply and consistentlyusing brief commands like the following:

      ROBOCOPY /JOB:SB/JOB:P1

      ROBOCOPY /JOB:SB/JOB:P2

   Etc…

This is just anintroduction to Robocopy Job Files with simple and straightforward examples,but their flexibility an open-endedness enables large and complicated jobs tobe created and managed with ease.

Scheduling Robocopy Jobs

You can create Robocopy jobs that runregularly and automatically in the background to maintain local mirrors ofremote directory trees. In Windows 2000, use theAT command, or use theSOONcommand with the Windows 2000 Schedule service. (TheSOON command runs Soon.exe, aWindows® 2000 Resource Kit tool named Near-Future Command Scheduler.)

By default, the Schedule service logs on asthe system account for the local system, which has no network access. Scheduledjobs run in the same context as the Schedule service. To run a scheduledRobocopy job, however, Robocopy must connect to network drives, which requiressome additional configuration. The following sections describe two ways toaccomplish this.

Using the Local System Account

You can leave the Schedule service runningin the context of the local system account. You can then schedule batch filesby using the following commands:

    NET USE \\remoteserver\IPC$ /USER:userid password

    ROBOCOPY\\remoteserver\sourcepath \\localserver\destpath ...

    NET USE \\remoteserver\IPC$ /DEL

Within each job, credentials with remoteservers are validated by connecting to the IPC$ (Interprocess Communication)share on remote computers using an appropriate user account, rather than thelocal system account. The disadvantage of this approach is that user passwordsare stored in the batch files; however, passwords can be protected by storingthe batch files on an NTFS volume, and setting appropriate NTFS permissions onthe batch files.

Using a User Account

You can configure the Schedule service tolog on as a user account. Once the user account has been granted appropriateaccess to source and destination servers, you can schedule Robocopy jobs tocopy files between them.

To configure theSchedule service to log on as a user account

    1.   In Services in Control Panel, clickSchedule, and then clickStartup.

    2.   In theStartupType box, clickAutomatic orManual.

    3.   In theLogOn As box, select the account in which to run the service, and specify thecorrect logon password.

Because drive mappings can be changed by users,it is more reliable to use UNC names for source and destination directories inscheduled Robocopy jobs. For example:

ROBOCOPY \\server1\share1\source\\server2\share2\dest …

The ATcommand and the Schedule service are documented in Windows 2000 onlineHelp. TheSOON command is documentedin theMicrosoft® Windows® 2000 Resource Kit.

Monitoringa Directory Tree

Usingthe/MON:n and/MOT:mswitches you can Monitor the source directory tree for changes, and copychanges as and when they occur. The/MON:n switch specifies the minimumnumber of changes that must occur before running again. The/MOT:m switch specifies the minimum time,in minutes, that must elapse before running again.

Ifyou only specify one of these switches, the other is assumed to have a value of1.

WhenMonitoring is specified, Robocopy never terminates. Instead, it enters a loopthat performs a normal Robocopy pass and then monitors the source directorytree for changes, until bothn changes have been detected andmminutes have elapsed. When both conditions are met, another Robocopy pass isstarted. This whole process of copying and monitoring is repeated, adinfinitum, until the user manually terminates the Robocopy process.

Asa minimum, Robocopy monitors the source directory tree for changes to file anddirectory names, sizes, and last write times. If attributes are to be copiedRobocopy will also monitor the tree for attribute changes. Similarly, ifsecurity information is to be copied, Robocopy will also monitor the tree forsecurity changes.

Consequently,a user performing an edit and saving a single new file, for example, may causemultiple changes of various types to be reported back to Robocopy. Thereforesome experimentation may be required to determine appropriate threshold valuesfor/MON and/MOT for eachRobocopy job, especially those monitoring busy trees.

Controlling Bandwidth Usage

Usingthe/RH:hhmm-hhmmswitch to specify Robocopy’s Run Hours you can definea time slot in which starting new copies is allowed; outside of this time slotnew copies will not be started, and Robocopy will sleep, waiting for the starttime to come around.

Bothtimes must be in 24-hour format, must be exactly 4 digits long  in the range 0000 to 2359, and must bedifferent so as to specify a minimum two-minute window in which new copies maybe started.

Forexample/RH:2200-0600 would specifythat copies can be started when the local system time is between 10 p.m. and 6a.m. (or, to be exact, between 10:00:00 p.m. and 06:00:59 a.m., as Robocopyonly looks at the hours and minutes components of the local system time whendeciding if starting new copies is allowed).

Bydefault Robocopy will check to see if it is within the defined Run Hours timeslot at the start of each Robocopy pass (i.e. before starting the initial copypass; and, if/MON or/MOTwere used, at the start of each subsequent copy pass).

Youshould use the/PFswitch if youwould like the Run Hours check to be performed before each individual file copyis started.

Oncea copy  is actually started it alwaysruns to completion, and therefore it is probable that a copy pass or file copythat starts close to the end of the Run Hours time slot will not complete untilsome time after the end time specified. Experimentation may therefore berequired to determine an appropriate end time for your needs.

Themost obvious use of/RH is to limitRobocopy’s copy activity to a time slot that is outside of normal businesshours (e.g./RH:2200-0600), to limitRobocopy’s use of   network bandwidth andimprove network performance for interactive users during the day. This isparticularly useful for Robocopy jobs that run for extended periods of time,for example those that process very large trees, or Monitoring jobs.

However,you can also use/RHto schedule ajob to start at a later time. For example, you could start Robocopy in acommand window with/RH:1900-1901just before you leave work to go home, and the job would start copying at 7pm, and run overnight.

Onvery slow links heavy Robocopy activity can easily consume large percentages tothe available network bandwidth, and seriously impact network performance. Insuch a case you can use the /IPG:n switch to specify an Inter-PacketGap ofn milliseconds.

Robocopyusually copies files in 64 kilobyte packets with no delay between receiving apacket and requesting the next. When/IPG is used Robocopy will wait for the giventime interval before requesting the next packet, thereby freeing up networkbandwidth. Again, experimentation may be required to determine an appropiatevalue for/IPG.

OutputLog

During a run, Robocopy creates an OutputLog that comprises a Job Header detailing the command line arguments used forthe job, a list of files and directories processed during the job, and a JobSummary that shows totals copied, etc. By default, Output Log is written to thecommand prompt. This output can be redirected to a file, either by using thestandard command-line operators (> or >>), or by using one of thecommand-line options:

·   /LOG:fileredirects output to the specified file, overwriting the file if it alreadyexists.

·   /LOG+:fileredirects output to the specified file, appending it to the file if it alreadyexists.

You can also use/TEE inconjunction with one of the above options. This causes Robocopy to log itsoutput to both the command prompt (for visual progress monitoring) and thespecified file (for a permanent record of the Robocopy run).

Aside from error reporting and retries,Robocopy produces one line of output per source file or directory. Lines fordirectories show the number of files in that directory specified for copying(where known) and the full path of the directory. Lines for files indicate thename of the file, the size of the file, and what was done with the file.

One line is also generated for eachMismatched file and directory and each Extra file and directory in thedestination. Lines for Extra files include the full path and name of the file.

By default, the only Extra files reportedare those that match files specified for copying on the command line. In mostcases, this is more efficient. For example, if you are refreshing CPP files,you probably do not need information about TXTfiles in the destination. If you want a list of all Extra files in thedestination, regardless of their type, use the/X switch.

No output is produced for skipped files. Toobtain a verbose listing that shows all source files specified for copying onthe command line, including skipped files, use the/V switch.

Robocopy provides copy progress information(% copied) by default. You can use the/NPswitch to suppress the display of progress information. This can be useful whenoutput is redirected to a file.

To see the start time of each file copy andthe estimated time of completion based on the observed throughput of previouscopies, use the/ETA switch. Times are displayed after thefile name in the format HH:MM  – >HH:MM (start  – >finish).

Finally, to obtain only a list of the filesthat would be copied (without actually copying them), use the/L switch.

This defaultcontents of the output log can be modified using the following command lineswitches :

·        /TS displays the file timestamps forevery file processed.

·        /FP replaces simple file names with fullfile pathnames in the output.

·        /NS (No Sizes) suppresses output of filesizes.

·        /NC (No Classes) suppresses output offile class “Text Tags” (see below).

·        /NDL(No Directory List) suppressesoutput of the directory list. When/NDLis used, full pathnames of processed files are logged instead of the simplefile name, so that problems can be pinpointed. Because of this, note that logfiles can actually increase in size if/NDLis used. Directories deleted by/PURGE(or whichwould be deleted if/L was omitted, if/PURGE and/L were bothused) are always logged even if /NDLis used.

·        /NFL(No File List) suppresses output offiles processed. File copy failures are still logged even if/NFL is used, so that problems can beisolated. Files deleted by/PURGE(or which would be deleted if /L wasomitted, if/PURGE and/L were both used) are always loggedeven if/NFL is used.

·        /NJH(No Job Header) suppresses outputof the job header.

·        /NJS(No Job Summary) suppresses outputof the job summary.

Combinations ofthese switches allow quite a bit of flexibility in terms of what is logged. Forexample, you could use/NDL /NC /NSto produce a list of just the full pathnames of files that were processedduring the run, or you could use/NDL/NFL to produce just the summary report for the run (see “Run Summary”below).

Text Tags

Each line in the output log begins with abrief text tag, which is formatted according to the following rules:

·    Allcapital letters indicate an anomaly that should be investigated.

·    Initialcapital letters indicate a file that was selected for copying.

·    Alllowercase letters indicate a file that was skipped (displayed only if the/V switch is used).

The text tags that indicate copying areleft-aligned. Tags that indicate skipping are right-aligned. Tags that indicateanomalies are placed farther to the left than other tags. Error messages alwaysstart in the first column. This arrangement simplifies the task of scanningthrough even a verbose listing, and makes it easier to identify new downloads,anomalies, and network errors.

If few files are copied, the left margin ofthe output log is mostly blank. Copied files and anomalies are easily spottednon-blank entries in the left margin of the output log.

Tags for Files

The following table lists the tags thatapply to files.

Tags for Directories

The following table lists the tags thatapply to directories.

Run Summary

If you have not specified the /NJS (No Job Summary) switch, thenbefore Robocopy stops, it displays a summary of its activities at the commandprompt (or redirects the information to a file). This output summarizes thevolume of data processed in the following format:

The first column of the run summaryindicates the total number of files and directories processed, the total sizeof source files matching the file names specified for copying, and the totaltime taken by the operation. The remaining columns provide a breakdown of thetotals, as described in the following table.

The Times line of the summary providestiming information for the run, as described in the following table. Times aredisplayed in HH:MM:SS format.

Large times in the FAILED column usually indicatenetwork problems.

Finally, if files were copied, the Speed linesshow throughput information, calculated by dividing the volume of data copiedby the time spent copying. The same data is displayed twice: first in bytes persecond (bps), and then in megabytes per minute (mb/min).

Return Code

The return code fromRobocopy is a bit map, defined as follows:

You can use thisinformation in a batch file to report the most serious anomalies, as follows:

if errorlevel 16 echo ***FATAL ERROR***  & goto end

if errorlevel 8  echo**FAILED COPIES**  & goto end

if errorlevel 4  echo*MISMATCHES*       & goto end

if errorlevel 2  echoEXTRA FILES        & goto end

if errorlevel 1  echoCopy successful    & goto end

if errorlevel 0  echo--no change--      & goto end

:end

Alternatively, full detailsof the return code could be reported as follows:

if errorlevel 16 echo  ***FATAL ERROR***  & goto end

if errorlevel 15  echoFAIL MISM XTRA COPY & gotoend

if errorlevel 14  echoFAIL MISM XTRA      & goto end

if errorlevel 13  echoFAIL MISM      COPY& goto end

if errorlevel 12  echoFAIL MISM           & goto end

if errorlevel 11  echoFAIL      XTRA COPY& goto end

if errorlevel 10  echoFAIL      XTRA      & goto end

if errorlevel  9  echo FAIL           COPY& goto end

if errorlevel  8  echo FAIL                & goto end

if errorlevel  7  echo     MISM XTRA COPY &goto end

if errorlevel  6  echo     MISM XTRA      & goto end

if errorlevel  5  echo     MISM      COPY & goto end

if errorlevel  4  echo     MISM           & goto end

if errorlevel  3  echo          XTRA COPY & gotoend

if errorlevel  2  echo          XTRA      & goto end

if errorlevel  1  echo                COPY& goto end

if errorlevel  0  echo   --no change--    & goto end

:end

Feedback

For questions or feedback concerning thistool, please contact rkinput_microsoft.com.

If you want to report a problem encounteredwhen using Robocopy, please supply the following information.

·    Versionnumber

·    Operatingsystem and Service Pack for all computers

·    Filesystem

·    CompleteRobocopy command line or batch file

·    Outputlog

·    Directorylistings

·    Dr.Watson log (for application errors)

·    Methodof running Robocopy (from the command prompt, using Schedule service, and soon)

·    Useraccount information.

© 1985 – 2003 Microsoft Corporation. All rightsreserved.