Jump to content

Robocopy

From Wikipedia, the free encyclopedia

This is an old revision of this page, as edited by MrOllie (talk | contribs) at 15:29, 20 March 2021. The present address (URL) is a permanent link to this revision, which may differ significantly from the current revision.

Robocopy
Developer(s)Microsoft
Initial release1996, 27–28 years ago
Stable release
10.0.19041.1 / December 7, 2019; 5 years ago (2019-12-07)
Operating systemWindows NT 4 and later
TypeCommand
LicenseFreeware
Websitedocs.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy

Robocopy, for "Robust File Copy", is a command-line directory and/or file replication command for Microsoft Windows. Robocopy functionally replaces Xcopy, with more options. Created by Kevin Allen[1] and first released as part of the Windows NT 4.0 Resource Kit, it has been a standard feature of Windows since Windows Vista and Windows Server 2008. The command is robocopy.

Features

Robocopy is noted for capabilities above and beyond the built-in Windows copy and xcopy commands, including the following, some requiring appropriate command-line options:

  • Ability to tolerate network interruptions and resume copy (incomplete files are marked with a date stamp of 1970-01-01 and contain a recovery record so Robocopy knows where to continue from).
  • Ability to skip NTFS junction points which can cause copying failures because of infinite loops (/XJ)
  • Ability to copy file data and attributes correctly, and to preserve original timestamps, as well as NTFS ACLs, owner information, and audit information using the /COPYALL or /COPY: command line switches.
  • Beginning with the XP026 version, the ability to copy folder (or directory) date and timestamps (/DCOPY:T), even with the ability to update folder timestamps (copied from existing folders) on folders already created from previous versions (that did not copy the folder date and timestamps).
  • Ability to assert the Windows NT "backup right" (/B) so an administrator may copy an entire directory, including files denied readability to the administrator.
  • Persistence by default, with a programmable number of automatic retries if a file cannot be copied.
  • A "mirror" mode, which keeps trees synchronised by also deleting files in the destination that are not present in the source.
  • Ability to skip files already in the destination folder with identical size and timestamp.
  • A continuously updated command-line progress indicator.
  • Ability to copy paths exceeding 259 characters — up to a theoretical limit of about 32,000 characters — without errors.[2]
  • Multithreaded copying introduced with Windows 7 and Windows Server 2008 R2.[3]
  • Return code[4] on program termination for batch file usage.

Compression

Since Windows Server 2019 and Windows 10, a compression option is available in robocopy when copying across a network. With this switch, if the destination computer supports SMB compression and the files being copied are very compressible, there may be significant improvements to performance. The SMB compression adds inline whitespace compression to file transfers. Compression is also available with the xcopy command and Hyper-V Live Migration with SMB.[5][6]

Examples of use

Here are some examples of usage, which is not case-sensitive. If more than one option is specified, they must be separated by spaces.

  • Copy directory contents of the source Directory A to the destination Directory B (including file data, attributes and timestamps), recursively with empty directories (/E):
Robocopy "C:\Directory A" "C:\Directory B" /E

If directory names have non-standard characters, such as spaces, they must be enclosed in double quotes, as is usual in the command line.

  • Copy directory recursively (/E), copy all file information (/COPYALL, equivalent to /COPY:DATSOU, D=Data, A=Attributes, T=Timestamps, S=Security=NTFS ACLs, O=Owner info, U=Auditing info), do not retry locked files (/R:0) (the number of retries on failed copies default value is 1 million), preserve original directories' Timestamps (/DCOPY:T - requires version XP026 or later):
Robocopy C:\A C:\B /COPYALL /E /R:0 /DCOPY:T
  • Mirror A to B, destroying any files in B that are not present in A (/MIR), copy files in resume mode (/Z) in case network connection is lost:
Robocopy C:\A \\backupserver\B /MIR /Z

For the full reference, see the Microsoft TechNet Robocopy page.[7]

Syntactic focus on copying folders

Robocopy syntax is markedly different from its predecessors (copy and xcopy), in that it accepts only folder names, without trailing backslash, as its source and destination arguments. File names and wildcard characters (such as * and ?) are not valid as source or destination arguments; files may be selected or excluded using the optional "file" filtering argument (which supports wildcards) along with various other options.[8]

For example, to copy two files from folder c:\bar to c:\baz, the following syntax is used: 

 robocopy c:\bar c:\baz file1.txt file2.db

And to copy all PDF files from c:\bar to c:\baz: 

 robocopy c:\bar c:\baz *.pdf

The files named are copied only from the folder selected for copying; fully qualified path names are not supported.

CAUTION: A long standing issue with Robocopy means that if you back up from the root folder of a drive [ eg, robocopy d:\ b:\d-backup\ ....], the destination files will be given attributes including SH. This means that they will be invisible to normal access (including DIR in cmd.exe). To fix this, add "/a-:SH" to the robocopy command line - or do an ATTRIB command to remove them afterwards.

Output

Robocopy outputs to the screen, or optionally to a log file, the names of all the directories it encounters, in alphabetical order. Each name is preceded by the number of files in the directory that fulfill the criteria for being copied. If the directory does not yet exist in the target, it is marked "New Dir"; if the directory is empty and the /E option is not used, or it contains no files meeting the criteria, a new directory will not be created.

If the /NFL (no file names in log) option is not used, the files being copied will be listed after the name of the directory they are in.

At the end of the output is a table giving numbers of directories, files, and bytes. For each of these, the table gives the total number found in the source, the number copied (including directories marked "New Dir" even if they are not copied), the number skipped (because they already exist in the target), and the number of mismatches, FAILED, and extras. "Failed" can mean that there was an I/O error that prevented a file being copied, or that access was denied. There is also a row of time taken (in which the time spent on failed files seems to be in the wrong column).

Bandwidth throttling

Robocopy's "inter-packet gap" (IPG) option allows some control over the network bandwidth used in a session. In theory, the following formula expresses the delay (D, in milliseconds) required to simulate a desired bandwidth (BD, in kilobits per second), over a network link with an available bandwidth of BA kbps:

In practice however, some experimentation is usually required to find a suitable delay, due to factors such as the nature and volume of other traffic on the network. The methodology employed by the IPG option may not offer the same level of control provided by some other bandwidth throttling technologies, such as BITS (which is used by Windows Update and BranchCache).

Limitations

  • Robocopy does not copy open files. Any process may open files for exclusive read access by withholding the FILE_SHARE_READ[9] flag during opening. Even Robocopy's Backup mode will not touch those files. (Backup mode instead runs Robocopy as a "Backup Operator". This allows Robocopy to override permissions settings, specifically, NTFS ACLs).[10][11] Normally Volume Shadow Copy Service is used for such situations, but Robocopy does not use it. Consequently, Robocopy is not suitable for backing up live operating system volumes. However, a separate utility such as ShadowSpawn[12] (Free, Open Sourced, and MIT Licensed) or GSCopyPro[13] ($30 - $50) or DiskShadow.exe[14] (included with Windows Server 2008), can be used beforehand to create a shadow copy of a given volume, which Robocopy can then back up.
  • Robocopy versions on systems older than Windows Vista do not mirror properly. They ignore changed security attributes of previously mirrored files.[15][16]
  • When specifying the /MT[:n] option to enable multithreaded copying, the /NP option to disable reporting of the progress percentage for files is ignored. By default the MT switch provides 8 threads. The n is the number of threads you specify if you do not want to use the default.[17]

GUI

Although Robocopy itself is a command-line tool, Microsoft TechNet provides a GUI front-end called Robocopy GUI. It was developed by Derk Benisch, a systems engineer with the MSN Search group at Microsoft, and required .NET Framework 2.0.[18] It includes a copy of Robocopy version XP026.

There are non-Microsoft GUIs for Robocopy:

  • "WinRoboCopy" revision 1.3.5953.40896 released on April 19, 2016.[19]
  • "Easy RoboCopy" latest version 1.0.15 released on January 8, 2018.[20]
  • A program by SH-Soft, also called "Robocopy GUI" v1.0.0.24 (October 8, 2005).[21]
  • Cinchoo EazyCopy v1.0.0.14 (February 11, 2021)
  • RoboCop, Robocopy GUI Skin and script generator with Progress Monitoring, 10 September 2015.[22]

Ken Tamaru of Microsoft developed a copying program with functionality similar to Robocopy, called RichCopy, discontinued in 2010. It is not based on Robocopy, and does not require .NET Framework.[23]

Versions

Several versions of Robocopy do not report the version number when executing robocopy /? on the command line. However, their version is stored inside the executable itself and can be queried with PowerShell for example (gcm robocopy | fl *) or inside Windows Explorer by right-clicking on Robocopy.exe, selecting Properties, then clicking on the Details tab.

Product version File version Year Origin Other
1.54 - 1996 Windows NT 4.0 Resource Kit © 1996
1.70 - 1997 Windows NT Resource Kit
1.71 4.0.1.71 1997 Windows NT Resource Kit
1.95 4.0.1.95 1999 Windows 2000 Resource Kit
1.96 4.0.1.96 1999 Windows 2000 Resource Kit © 1995-1997
XP010 5.1.1.1010 2003 Windows 2003 Resource Kit
XP026 5.1.2600.26 2005 Downloaded with Robocopy GUI v.3.1.2; /DCOPY:T option introduced
XP027 5.1.10.1027 2008 Bundled with Windows Vista, Server 2008, Windows 7, Server 2008r2 © 1995-2004
6.1 6.1.7601 2009 KB2639043 © 2009
6.2 6.2.9200 2012 Bundled with Windows 8 © 2012
6.3 6.3.9600 2013 Bundled with Windows 8.1 © 2013
10.0 10.0.10240.16384 2015 Bundled with Windows 10 © 2015
10.0.16299 10.0.16299.15 2017 Bundled with Windows 10 1709 © 2017
10.0.17134 10.0.17134.1 2018 Bundled with Windows 10 1803 © 2018
10.0.17763 10.0.17763.1 2018 Bundled with Windows 10 1809 © 2018
10.0.18362 10.0.18362.1 2019 Bundled with Windows 10 1903 © 2019
10.0.19041.1 10.0.19041.1 2020 Bundled with Windows 10 20H2 © 2020

See also

References

  1. ^ "AMA with Dave Plummer, creator of Task Manager". Reddit.com. Retrieved 19 December 2020.
  2. ^ Lewis, Dick (15 November 2004). "Robocopy XP010 FAQ". Windows IT Pro. Penton Media. p. 2. Archived from the original on 9 October 2012.
  3. ^ "Multi-threaded robocopy for faster copies - Grant Holliday's Blog - Site Home - MSDN Blogs". Blogs.msdn.com. 2009-10-23. Retrieved 2012-11-11.
  4. ^ "Return codes that are used by the Robocopy utility in Windows Server 2008 or Windows Server 2008 R2". Support.microsoft.com. 2012-02-17. Retrieved 2012-11-11.
  5. ^ Sander Berkouwer. "RoboCopy supports Copying Files over SMB with Compression on Windows Server 2019, and beyond". dirteam.com. Retrieved 14 February 2021.
  6. ^ Smith, Russell (27 November 2020). "SMB Compression Lowers Bandwidth and Improves Copy Times in Windows Server and Azure". Petri.
  7. ^ "Robocopy". Microsoft Technet. 7 June 2020.
  8. ^ "Robocopy". Microsoft Docs. Microsoft. 31 October 2016. Retrieved 14 January 2019.
  9. ^ https://msdn.microsoft.com/en-us/library/aa363858.aspx "CreateFile function". MSDN. FILE_SHARE_READ [...] Enables subsequent open operations on a file or device to request read access. Otherwise, other processes cannot open the file or device if they request read access.
  10. ^ "Robocopy.exe - Robust File Copy Utility - Version XP010" (PDF). Backup mode copies [...] enable you to copy some files as a Backup Operator that you would not be able to copy as a normal user.
  11. ^ "Default groups". Microsoft TechNet. Backup Operators [...] Members of this group can back up and restore all files [...], regardless of their own individual permissions on those files.
  12. ^ "ShadowSpawn". Craig Andera. Retrieved 2015-07-14. ShadowSpawn.exe is an open source MIT licensed tool that creates and manages shadow copies.
  13. ^ "GSCopyPro". GuruSquad. Retrieved 2013-03-06. gscopypro.exe is a tool that works similar to robocopy but has the ability to copy open files.
  14. ^ "Diskshadow". Microsoft TechNet. Retrieved 2013-03-06. DiskShadow.exe is a tool that exposes the functionality offered by the Volume Shadow Copy Service (VSS).
  15. ^ "Microsoft's Robocopy compromise". ZDNet. 2008-08-04. Archived from the original on March 17, 2010. Retrieved 2012-11-11.
  16. ^ "Ugly bug in Robocopy - ignoring security on file level - Martin Zugec blog". Msmvps.com. 2008-03-03. Retrieved 2012-11-11.
  17. ^ "Robocopy's /MT option disables /NP option". Microsoft TechNet. 2009-12-13. Retrieved 2014-02-26.
  18. ^ Joshua Hoffman (November 2006). "Utility Spotlight Robocopy GUI". TechNet Magazine. Microsoft Corporation and CMP Media, LLC. Retrieved 2008-07-17.
  19. ^ "WinRoboCopy - UpWay2Late.com Software". Upway2late.com. Retrieved 2012-11-11.
  20. ^ "Easy RoboCopy". TribbleSoft. Retrieved 2017-10-03.
  21. ^ "SH-RoboCopy GUI". SH-Soft. Retrieved 2012-11-23.
  22. ^ turnssoft (10 September 2015). "RoboCop RoboCopy". SourceForge.
  23. ^ Hoffman, Joshua (November 2006). "Free Utility: RichCopy, an Advanced Alternative to RoboCopy". TechNet Magazine. Microsoft Corporation and CMP Media, LLC. Retrieved 2008-07-17.
Wikibooks has a book on the topic of: Guide to Windows Commands
Retrieved from "https://en.wikipedia.org/enwiki/w/index.php?title=Robocopy&oldid=1013193705"