gorobocopy

README

go-robocopy

Disclaimer

This is an unofficial wrapper for robocopy. There is no affiliation with Microsoft or any of its subsidiaries in any way. Use it at your own risk.

---

Robocopy or Robust File Copy is a command line tool developed by Microsoft for copying files and directories from one location to another.

This is an unofficial wrapper written in Go to programmatically produce a robocopy command and execute it.

[!IMPORTANT] This library can only be compiled for Windows targets as it relies on the robocopy command.

Installation

You can install the package using the go get command.

go get github.com/aggellos2001/go-robocopy

After that you need to import the module in your code.

import (
    gorobocopy "github.com/aggellos2001/go-robocopy"
)

Examples

You can create a new command instance by calling the NewRobocopy constructor:

cmd := gorobocopy.NewRobocopy(
    "C:\\source",
    "D:\\destination",
    "*.*",
)

You can then set some options for the command:

cmd.SetCopyOptions(&gorobocopy.CopyOptions{
    E:    true,
    Mt:   4,
    Copy: copyflags.D | copyflags.A | copyflags.T,
    }
)

Finally, you can execute the command. You can specify the stdin, stdout and stderr in the parameters or leave them as nil if you want to suppress the console input/output.

cmd.Run(nil,nil,nil)

You can also get the command object and call it yourself however you like. It returns a pointer to a *exec.Cmd object.

cmd.GetCommand()

Also you can get the slice containing all the arguments to manually create the command if you please.

cmd.GetCommandArgs()

Documentation

Index

• type CopyFileThrottlingOptions
• type CopyOptions
• type ExitCode
  • func (e ExitCode) String() string
• type FileSelectionOptions
• type JobOptions
• type LoggingOptions
• type RetryOptions
• type Robocopy
  • func NewRobocopy(sourceDir, destinationDir, file string) *Robocopy
  • func (r *Robocopy) GetCommand() *exec.Cmd
  • func (r *Robocopy) GetCommandArgs() (command []string)
  • func (r *Robocopy) GetExitCode() ExitCode
  • func (r *Robocopy) Run(stdin io.Reader, stdout, stderr io.Writer)
  • func (r *Robocopy) SetCopyOptions(opts *CopyOptions)
  • func (r *Robocopy) SetFileSelectionOptions(opts *FileSelectionOptions)
  • func (r *Robocopy) SetJobOptions(opts *JobOptions)
  • func (r *Robocopy) SetLoggingOptions(opts *LoggingOptions)
  • func (r *Robocopy) SetRetryOptions(opts *RetryOptions)
  • func (r *Robocopy) SetThrottlingOptions(opts *CopyFileThrottlingOptions)

Types

type CopyFileThrottlingOptions

type CopyFileThrottlingOptions struct {
	// [/iomaxsize:n[kmg]] The requested max i/o size per read/write cycle in n kilobytes, megabytes, or gigabytes.
	Iomaxsize types.Pair[int, unitflags.UnitFlags]
	// [/iorate:<n>[kmg]] The requested i/o rate in n kilobytes megabytes, or gigabytes per second.
	Iorate types.Pair[int, unitflags.UnitFlags]
	// [/threshold:<n>[kmg]] The file size threshold for throttling in n kilobytes, megabytes, or gigabytes.
	Threshold types.Pair[int, unitflags.UnitFlags]
}

These throttling options are used to specify the maximum I/O bandwidth that Robocopy allows to be used in bytes per second. If not specifying in bytes per second, whole numbers can be used if k, m, or g are specified. The minimum I/O bandwidth that is throttled is 524288 bytes even if a lesser value is specified.

type CopyOptions

type CopyOptions struct {
	// [/s] Copies subdirectories. This option automatically excludes empty directories.
	S bool
	// [/e] Copies subdirectories. This option automatically includes empty directories.
	E bool
	// [/lev:n] Copies only the top n levels of the source directory tree.
	Lev int
	// [/z] Copies files in restartable mode. In restartable mode, should a file copy be interrupted, robocopy can pick up where it left off rather than recopying the entire file.
	Z bool
	// [/b] Copies files in backup mode. In backup mode, robocopy overrides file and folder permission settings (ACLs), which might otherwise block access.
	B bool
	// [/zb] Copies files in restartable mode. If file access is denied, switches to backup mode.
	Zb bool
	// [/j] Copies using unbuffered I/O (recommended for large files).
	J bool
	// [/efsraw] Copies all encrypted files in EFS RAW mode.
	EsfRaw bool
	// [/copy:<copyflags>] Specifies which file properties to copy. The valid values for this option are:
	// D - Data, A - Attributes, T - Time stamps, X - Skip alt data streams, S - NTFS access control list (ACL), O - Owner information, U - Auditing information
	// The default value for the /COPY option is DAT (data, attributes, and time stamps). The X flag is ignored if either /B or /ZB is used.
	Copy copyflags.CopyFlags
	// [/dcopy:<copyflags>] Specifies what to copy in directories. The valid values for this option are:
	// D - Data, A - Attributes, T - Time stamps, E - Extended attribute, X - Skip alt data streams
	// The default value for this option is DA (data and attributes).
	Dcopy dcopyflags.DCopyFlags
	// [/sec] Copies files with security (equivalent to /copy:DATS).
	Sec bool
	// [/copyall] Copies all file information (equivalent to /copy:DATSOU).
	CopyAll bool
	// [/nocopy] Copies no file information (useful with /purge).
	NoCopy bool
	// [/secfix] Fixes file security on all files, even skipped ones.
	SecFix bool
	// [/timfix] Fixes file times on all files, even skipped ones.
	TimFix bool
	// [/purge] Deletes destination files and directories that no longer exist in the source. Using this option with the /e option and a destination directory, allows the destination directory security settings to not be overwritten.
	Purge bool
	// [/mir]  	Mirrors a directory tree (equivalent to /e plus /purge). Using this option with the /e option and a destination directory, overwrites the destination directory security settings.
	Mir bool
	// [/mov] Moves files, and deletes them from the source after they're copied.
	Mov bool
	// [/move] Moves files and directories, and deletes them from the source after they're copied.
	Move bool
	// [/a+:[RASHCNET]]
	// Adds the specified attributes to copied files. The valid values for this option are:
	// R - Read only, A - Archive, S - System, H - Hidden, C - Compressed, N - Not content indexed, E - Encrypted, T - Temporary, O - Offline
	APlus aflags.AFlags
	// [/a-:[RASHCNETO]]
	// Removes the specified attributes from copied files. The valid values for this option are:
	// Everything is the same as [/a+:] with the only addintional value O - Offline
	AMinus aflags.AFlags
	// [/create] Creates a directory tree and zero-length files only.
	Create bool
	// [/fat] Creates destination files by using 8.3 character-length FAT file names only.
	Fat bool
	// [/256] Turns off support for paths longer than 256 characters.
	NoMoreThan256 bool
	// [/mon:n] Monitors the source and runs again when more than n changes are detected.
	Mon int
	// [/mot:m] Monitors the source and runs again in m minutes if changes are detected.
	Mot int
	// [/rh:hhmm-hhmm] Specifies run times when new copies can be started.
	Rh string
	// [/pf] Checks run times on a per file (not per-pass) basis.
	Pf bool
	// [/ipg:n] Specifies the inter-packet gap to free bandwidth on slow lines.
	Ipg int
	// [/sj] Copies junctions (soft-links) to the destination path instead of link targets.
	Sj bool
	// [/sl] Don't follow symbolic links and instead create a copy of the link.
	Sl bool
	// [/mt:n] Creates multi-threaded copies with n threads. n must be an integer between 1 and 128. The default value for n is 8. For better performance, redirect your output using /log option.
	//The /mt parameter can't be used with the /ipg and /efsraw parameters.
	Mt int
	// [/nodcopy] Copies no directory info (the default /dcopy:DA is done).
	Nodcopy bool
	// [/nooffload] Copies files without using the Windows Copy Offload mechanism.
	Nooffload bool
	// [/compress] Requests network compression during file transfer, if applicable.
	Compress bool
	// [/sparse] Enables retaining the sparse state of files during copy.
	Sparse bool
}

type ExitCode

type ExitCode int

const (
	// No files were copied. No failure was encountered. No files were mismatched.
	// The files already exist in the destination directory; therefore, the copy operation was skipped.
	AlreadyExist ExitCode = iota
	// All files were copied successfully.
	AllFilesCopied
	// There are some additional files in the destination directory that aren't present in the source directory. No files were copied.
	AdditionalFilesOnDest
	// Some files were copied. Additional files were present. No failure was encountered.
	SomeFilesCopied

	// Some files were copied. Some files were mismatched. No failure was encountered.
	SomeFilesMismatched
	// Additional files and mismatched files exist. No files were copied and no failures were encountered meaning that the files already exist in the destination directory.
	AdditionalAndMismatchedFiles
	// Files were copied, a file mismatch was present, and additional files were present.
	FilesCopiedMismatchedAndAdditional
	// Several files didn't copy.
	SeveralFilesDidntCopy
)

func (ExitCode) String

func (e ExitCode) String() string

type FileSelectionOptions

type FileSelectionOptions struct {
	// [/a] Copies only files for which the Archive attribute is set.
	A bool
	// [/m] Copies only files for which the Archive attribute is set, and resets the Archive attribute.
	M bool
	// [/ia:[RASHCNETO]] Includes only files for which any of the specified attributes are set. The valid values for this option are:
	// R - Read only, A - Archive, S - System, H - Hidden, C - Compressed, N - Not content indexed, E - Encrypted, T - Temporary, O - Offline
	Ia aflags.AFlags
	// [//xa:[RASHCNETO]] Excludes files for which any of the specified attributes are set. The valid values for this option are the same as the [/ia] command.
	Xa aflags.AFlags
	// [/xf <filename>[...]] Excludes files that match the specified names or paths. Wildcard characters (* and ?) are supported.
	Xf []string
	// [/xd <directory>[...]] Excludes directories that match the specified names and paths.
	Xd []string
	// [/xc] Excludes existing files with the same timestamp, but different file sizes.
	Xc bool
	// [/xn] Source directory files newer than the destination are excluded from the copy.
	Xn bool
	// [/xo] Source directory files older than the destination are excluded from the copy.
	Xo bool
	// [/xx] Excludes extra files and directories present in the destination but not the source. Excluding extra files won't delete files from the destination.
	Xx bool
	// [/xl] Excludes "lonely" files and directories present in the source but not the destination. Excluding lonely files prevents any new files from being added to the destination.
	Xl bool
	// [/im] Include modified files (differing change times).
	Im bool
	// [/is] Includes the same files. Same files are identical in name, size, times, and all attributes.
	Is bool
	// [/it] Includes "tweaked" files. Tweaked files have the same name, size, and times, but different attributes.
	It bool
	// [/max:n] Specifies the maximum file size (to exclude files bigger than n bytes).
	Max int
	// [/min:n] Specifies the minimum file size (to exclude files smaller than n bytes).
	Min int
	// [/maxage:n] Specifies the maximum file age (to exclude files older than n days or date).
	Maxage int
	// [/minage:n] Specifies the minimum file age (exclude files newer than n days or date).
	Minage int
	// [/maxlad:n] Specifies the maximum last access date (excludes files unused since n).
	Maxlad int
	// [/minlad:n] Specifies the minimum last access date (excludes files used since n) If n is less than 1900, n specifies the number of days. Otherwise, n specifies a date in the format YYYYMMDD.
	Minlad int
	// [/xj] Excludes junction points, which are normally included by default.
	Xj bool
	// [/fft] Assumes FAT file times (two-second precision).
	Fft bool
	// [/dst] Compensates for one-hour DST time differences.
	Dst bool
	// [/xjd] Excludes junction points for directories.
	Xjd bool
	// [/xjf] Excludes junction points for files.
	Xjf bool
}

type JobOptions

type JobOptions struct {
	// [/job:jobname] Specifies that parameters are to be derived from the named job file. To run /job:jobname, you must first run the /save:jobname parameter to create the job file.
	Job string
	// [/save:jobname] Specifies that parameters are to be saved to the named job file. This must be ran before running /job:jobname. All copy, retry, and logging options must be specified before this parameter.
	Save string
	// [/quit] Quits after processing command line (to view parameters).
	Quit bool
	// [/nosd] Indicates that no source directory is specified.
	Nosd bool
	// [/nodd] Indicates that no destination directory is specified.
	Nodd bool
	// [/if] Includes the specified files.
	If bool
}

type LoggingOptions

type LoggingOptions struct {
	// [/l] Specifies that files are to be listed only (and not copied, deleted, or time stamped).
	L bool
	// [/x] Reports all extra files, not just the ones that are selected.
	X bool
	// [/v] Produces verbose output, and shows all skipped files.
	V bool
	// [/ts] Includes source file time stamps in the output.
	Ts bool
	// [/fp] Includes the full path names of the files in the output.
	Fp bool
	// [/bytes] Prints sizes, as bytes.
	Bytes bool
	// [/ns] Specifies that file sizes aren't to be logged.
	Ns bool
	// [/nc] Specifies that file classes aren't to be logged.
	Nc bool
	// [/nfl] Specifies that file names aren't to be logged.
	Nfl bool
	// [/ndl] Specifies that directory names aren't to be logged.
	Ndl bool
	// [/np] Specifies that the progress of the copying operation (the number of files or directories copied so far) won't be displayed.
	Np bool
	// [/eta] Shows the estimated time of arrival (ETA) of the copied files.
	Eta bool
	// [/log:logfile] Writes the status output to the log file (overwrites the existing log file).
	Log string
	// [/log+:logfile] Writes the status output to the log file (appends the output to the existing log file).
	LogPlus string
	// [/unilog:logfile] Writes the status output to the log file as unicode text (overwrites the existing log file).
	UniLog string
	// [/unilog+:logfile] Writes the status output to the log file as Unicode text (appends the output to the existing log file).
	UniLogPlus string
	// [/tee] Writes the status output to the console window, and to the log file.
	Tee bool
	// [/njh] Specifies that there's no job header.
	Njh bool
	// [/njs] Specifies that there's no job summary.
	Njs bool
	// [/unicode] Displays the status output as unicode text.
	Unicode bool
}

type RetryOptions

type RetryOptions struct {
	// [/r:<n>] Specifies the number of retries on failed copies. The default value of n is 1,000,000 (one million retries).
	R int
	// [/w:<n>] Specifies the wait time between retries, in seconds. The default value of n is 30 (wait time 30 seconds).
	W int
	// [/reg] Saves the values specified in the /r and /w options as default settings in the registry.
	Reg bool
	// [/tbd] Specifies that the system waits for share names to be defined (retry error 67).
	Tbd bool
	// [/lfsm] Operate in low free space mode that enables copy, pause, and resume (see Remarks).
	Lfsm bool
	// [/lfsm:<n>[kmg]] Specifies the floor size in n kilobytes, megabytes, or gigabytes.
	LfsmSize types.Pair[int, unitflags.UnitFlags]
}

type Robocopy

type Robocopy struct {
	// contains filtered or unexported fields
}

func NewRobocopy

func NewRobocopy(sourceDir, destinationDir, file string) *Robocopy

NewRobocopy returns a new robocopy instance with the default options applied.

func (*Robocopy) GetCommand

func (r *Robocopy) GetCommand() *exec.Cmd

Returns a ready-to-use exec.Cmd instance for the robocopy command. It is up to the caller to run the command and handle the output.

func (*Robocopy) GetCommandArgs

func (r *Robocopy) GetCommandArgs() (command []string)

Returns the command arguments for the robocopy command in the form of a string slice that can be used with exec.Command.

func (*Robocopy) GetExitCode

func (r *Robocopy) GetExitCode() ExitCode

func (*Robocopy) Run

func (r *Robocopy) Run(stdin io.Reader, stdout, stderr io.Writer)

Handles running the command and populating the exit code. You can set the stdin, stdout, and stderr of the command. If you set to nil, they will be set to the nul device (os.DevNull). You can check the exit code using the GetExitCode() function.

func (*Robocopy) SetCopyOptions

func (r *Robocopy) SetCopyOptions(opts *CopyOptions)

func (*Robocopy) SetFileSelectionOptions

func (r *Robocopy) SetFileSelectionOptions(opts *FileSelectionOptions)

func (*Robocopy) SetJobOptions

func (r *Robocopy) SetJobOptions(opts *JobOptions)

func (*Robocopy) SetLoggingOptions

func (r *Robocopy) SetLoggingOptions(opts *LoggingOptions)

func (*Robocopy) SetRetryOptions

func (r *Robocopy) SetRetryOptions(opts *RetryOptions)

func (*Robocopy) SetThrottlingOptions

func (r *Robocopy) SetThrottlingOptions(opts *CopyFileThrottlingOptions)