# FileSyncTask

Extends \Task

The FileSyncTask class copies files either to or from a remote host, or locally on the current host. It allows rsync to transfer the differences between two sets of files across the network connection, using an efficient checksum-search algorithm.

There are 4 different ways of using FileSyncTask:

1. For copying local files.
2. For copying from the local machine to a remote machine using a remote shell program as the transport (ssh).
3. For copying from a remote machine to the local machine using a remote shell program.
4. For listing files on a remote machine.

This is extended from Federico's original code, all his docs are kept in here below.

author | Federico Cargnelutti fede.carg@gmail.com
author | Anton Stöckl anton@stoeckl.de
version | $Revision$
package | phing.tasks.ext
see |
example |

### Methods

## Executes the rsync command and returns the exit code.

    executeCommand() : integer

throws |

### Response

`integer`

Return code from execution.

## Returns the rsync command line options.

    getCommand() : string

### Response

`string`

## Returns the textual description of the task

    getDescription() : string

inherited

### Response

`string`

The text description of the task

## Returns an error message based on a given error code.

    getErrorMessage(integer $code) : null|string

### Arguments

#### $code

`integer`

Error code

### Response

`null|string`

## Returns the location within the buildfile this task occurs. Used by {@link BuildException} to give detailed error messages.

    getLocation() : \Location

inherited

### Response

`\Location`

The location object describing the position of this task within the buildfile.

## Returns the owning target of this task.

    getOwningTarget() : \Target

inherited

### Response

`\Target`

The target object that owns this task

## Returns a reference to current project

    getProject() : \Project

inherited

### Response

`\Project`

Reference to current porject object

## Returns a name

    getRegisterSlot(string $slotName) : \RegisterSlot

inherited

### Arguments

#### $slotName

`string`

### Response

`\RegisterSlot`

## Returns the wrapper object for runtime configuration

    getRuntimeConfigurableWrapper() : \RuntimeConfigurable

inherited

### Response

`\RuntimeConfigurable`

The wrapper object used by this task

## Returns the name of task, used only for log messages

    getTaskName() : string

inherited

### Response

`string`

Name of this task

## Returns the name of the task under which it was invoked, usually the XML tagname

    getTaskType() : string

inherited

### Response

`string`

The type of this task (XML Tag)

## Called by the parser to let the task initialize properly.

    init()

inherited

Should throw a BuildException if something goes wrong with the build

This is abstract here, but may not be overloaded by subclasses.

throws |

## Logs a message with the given priority.

    log(string $msg, integer $level = \Project::MSG_INFO) : void

inherited

### Arguments

#### $msg

`string`

The message to be logged.

#### $level

`integer`

The message's priority at this message should have

## Called by the project to let the task do it's work. This method may be called more than once, if the task is invoked more than once. For example, if target1 and target2 both depend on target3, then running <em>phing target1 target2</em> will run all tasks in target3 twice.

    main()

inherited abstract

Should throw a BuildException if someting goes wrong with the build

This is abstract here. Must be overloaded by real tasks.

## Configure this task if it hasn't been done already.

    maybeConfigure()

inherited

## Perfrom this task

    perform()

inherited

throws |

## Makes backups into hierarchy based in $dir.

    setBackupDir( $dir) : void

### Arguments

#### $dir

``

## This changes the way rsync checks if the files have been changed and are in need of a transfer.

    setChecksum(boolean $checksum) : void

Without this option, rsync uses a "quick check" that (by default) checks if each file’s size and time of last modification match between the sender and receiver. This option changes this to compare a 128-bit checksum for each file that has a matching size.

### Arguments

#### $checksum

`boolean`

## Tells rsync to delete extraneous files from the receiving side, but only for the directories that are being synchronized. Files that are excluded from transfer are also excluded from being deleted.

    setDelete(boolean $delete) : void

### Arguments

#### $delete

`boolean`

## Sets a textual description of the task

    setDescription(string $desc)

inherited

### Arguments

#### $desc

`string`

The text describing the task

## Sets the destination directory. If the option remotehost is not included in the build.xml file, rsync will point to a local directory instead.

    setDestinationDir(string $dir) : void

### Arguments

#### $dir

`string`

## This makes rsync perform a trial run that doesn’t make any changes (and produces mostly the same output as a real run). It is most commonly used in combination with the -v, --verbose and/or -i, --itemize-changes options to see what an rsync command is going to do before one actually runs it.

    setDryRun(boolean $dryRun) : void

### Arguments

#### $dryRun

`boolean`

## Sets exclude matching pattern.

    setExclude(string $exclude) : void

### Arguments

#### $exclude

`string`

## Exclude files matching patterns from $file, Blank lines in $file and lines starting with ';' or '#' are ignored.

    setExcludeFile(string $file) : void

### Arguments

#### $file

`string`

## Sets the identity file for public key transfers.

    setIdentityFile( $identity) : void

### Arguments

#### $identity

``

## Sets the isRemoteConnection property.

    setIsRemoteConnection(boolean $isRemote) : void

### Arguments

#### $isRemote

`boolean`

## Requests a simple itemized list of the changes that are being made to each file, including attribute changes.

    setItemizeChanges(boolean $itemizeChanges) : void

### Arguments

#### $itemizeChanges

`boolean`

## Sets the location within the buildfile this task occurs. Called by the parser to set location information.

    setLocation(\Location $location)

inherited

### Arguments

#### $location

`\Location`

The location object describing the position of this task within the buildfile.

## Sets the command options.

    setOptions(string $options) : void

### Arguments

#### $options

`string`

## Sets the owning target this task belongs to.

    setOwningTarget(\Target $target)

inherited

### Arguments

#### $target

`\Target`

## References the project to the current component.

    setProject(\Project $project) : void

inherited

### Arguments

#### $project

`\Project`

The reference to the current project

## Sets the remote host.

    setRemoteHost(string $host) : void

### Arguments

#### $host

`string`

## This option allows you to provide a password for accessing a remote rsync daemon. Note that this option is only useful when accessing an rsync daemon using the built in transport, not when using a remote shell as the transport.

    setRemotePass(string $pass) : void

### Arguments

#### $pass

`string`

## Allows the user to choose an alternative remote shell program to use for communication between the local and remote copies of rsync. Typically, rsync is configured to use ssh by default, but you may prefer to use rsh on a local network.

    setRemoteShell(string $shell) : void

### Arguments

#### $shell

`string`

## Specifies the user to log in as on the remote machine. This also may be specified in the properties file.

    setRemoteUser(string $user) : void

### Arguments

#### $user

`string`

## Sets the path to the rsync command.

    setRsyncPath(string $path) : void

### Arguments

#### $path

`string`

## Sets the wrapper object this task should use for runtime configurable elements.

    setRuntimeConfigurableWrapper(\RuntimeConfigurable $wrapper)

inherited

### Arguments

#### $wrapper

`\RuntimeConfigurable`

The wrapper object this task should use

## Sets the source directory.

    setSourceDir(string $dir) : void

### Arguments

#### $dir

`string`

## Sets the name of this task for log messages

    setTaskName(string $name) : string

inherited

### Arguments

#### $name

`string`

### Response

`string`

A string representing the name of this task for log

## Sets the type of the task. Usually this is the name of the XML tag

    setTaskType( $name)

inherited

### Arguments

#### $name

``

## Increases the amount of information you are given during the transfer. By default, rsync works silently. A single -v will give you information about what files are being transferred and a brief summary at the end.

    setVerbose(boolean $verbose) : void

### Arguments

#### $verbose

`boolean`

### Properties

## Path to rsync command.

    rsyncPath : string

var |

### Type(s)

`string`

## Source directory.

    sourceDir : string

For remote sources this must contain user and host, e.g.: user@host:/my/source/dir

var |

### Type(s)

`string`

## Destination directory.

    destinationDir : string

For remote targets this must contain user and host, e.g.: user@host:/my/target/dir

var |

### Type(s)

`string`

## Remote host.

    remoteHost : string

var |

### Type(s)

`string`

## Rsync auth username.

    remoteUser : string

var |

### Type(s)

`string`

## Rsync auth password.

    remotePass : string

var |

### Type(s)

`string`

## Remote shell.

    remoteShell : string

var |

### Type(s)

`string`

## Exclude file matching pattern.

    exclude : string

Use comma seperated values to exclude multiple files/directories, e.g.: a,b

var |

### Type(s)

`string`

## Excluded patterns file.

    excludeFile : string

var |

### Type(s)

`string`

## This option creates a backup so users can rollback to an existing restore point. The remote directory is copied to a new directory specified by the user.

    backupDir : string

var |

### Type(s)

`string`

## Default command options.

    defaultOptions : string

r - recursive p - preserve permissions K - treat symlinked dir on receiver as dir z - compress l - copy symlinks as symlinks

var |

### Type(s)

`string`

## Command options.

    options : string

var |

### Type(s)

`string`

## Connection type.

    isRemoteConnection : boolean

var |

### Type(s)

`boolean`

## This option increases the amount of information you are given during the transfer. The verbose option set to true will give you information about what files are being transferred and a brief summary at the end.

    verbose : boolean

var |

### Type(s)

`boolean`

## This option makes rsync perform a trial run that doesn’t make any changes (and produces mostly the same output as a real run).

    dryRun : boolean

var |

### Type(s)

`boolean`

## This option makes requests a simple itemized list of the changes that are being made to each file, including attribute changes.

    itemizeChanges : boolean

var |

### Type(s)

`boolean`

## This option will cause rsync to skip files based on checksum, not mod-time & size.

    checksum : boolean

var |

### Type(s)

`boolean`

## This option deletes files that don't exist on sender.

    delete : boolean

var |

### Type(s)

`boolean`

## Identity file.

    identityFile : string

var |

### Type(s)

`string`

## Owning Target object

    target : \Target

inherited

var |

### Type(s)

`\Target`

## Description of the task

    description : string

inherited

var |

### Type(s)

`string`

## Internal taskname (req)

    taskType : string

inherited

var |

### Type(s)

`string`

## Taskname for logger

    taskName : string

inherited

var |

### Type(s)

`string`

## Stored buildfile location

    location : \Location

inherited

var |

### Type(s)

`\Location`

## Wrapper of the task

    wrapper : \RuntimeConfigurable

inherited

var |

### Type(s)

`\RuntimeConfigurable`

## Holds a reference to the project that a project component (a task, a target, etc.) belongs to

    project : \Project

inherited

var | A reference to the current project instance

### Type(s)

`\Project`