Syntax: rsync-dist.pl {options} [command]
commands that do changes on the server:
dist --dist -d
distribute files to remote host
to-attic --to-attic [dir]
move a directory (aka version) to the "attic" directory
from-attic --from-attic [dir]
move a directory (aka version) from the "attic" directory
back to the main directory (which is given by -p)
change-links --change-links -C [source,filemask/files]
change symbolic links on the remote server
--> see also "--last-dist"
add-links --add-links -A [source,files]
add links on the remote server
--> see also "--last-dist"
remove-links --remove-links [source,files]
remove links on the remote server
mirror --mirror [dist|d|links|l]
mirror the specified directory from the first
given host to all following ones.
Caution: you may delete data on the secondary
hosts that you wanted to keep, think twice before
running this command
The list of mirror-hosts may contain the directory
in the form "hostname/directory". With this it is possible
to distribute directories from the central mirror
(the first host in the list) to a different directory
on the other host. If the directory is not given
(no "/" is found in the hostname) it is the same as on the
central mirror
rm-lock --rm-lock [dist|d|links|l]
remove the lockfile in the "dist" or "links"
directory in case it was left behind due to an
error in the script
(for distribution or links)
force-rm-lock --force-rm-lock [dist|d|links|l]
like "rm-lock", but the lock file is removed
even when it was created by another user.
mk-lock --mk-lock [dist|d|links|l]
create the lockfile in the remote directory. This is
useful in order to lock the directory for other users
that run rsync-dist.pl when you want to modify files on
the remote-host manually.
(for distribution or links)
rebuild-last --rebuild-last
rebuild the "LAST" file on the remote server. This
file contains the name of the latest distribution
directory. When a new distribution is made, the
files are compared against the files of this directory.
When a file has not changed, a hard-link to this
directory is created. Note that this command creates
no lock-file on the remote host. You have to do this
yourself with the "--mk-lock" command before.
only for distribution directories
create-branch [name]{,source}
create a new branch on the server. The {,source} parameter is
optional. It is the name of the old branch from which new
branch is created. If {,source} is omitted, the branch
is created from trunk
expand-glob
if the --localpath parameter contains glob-expressions
list all the files that would be checked for transfer
when a dist command is issued
commands to inspect the server:
ls --ls [dist|d|links|l]
show the remote directory (for distribution or links)
cat-log --cat-log [dist|d|links|l]
show the logfile (for distribution or links)
tail-log --tail-log [dist|d|links|l,n]
show the last n lines of the logfile
(for distribution or links)
perl-log --perl-log [dist|d|links|l]
similar to --cat-log, but dump the logfile as a
perl-structure to the screen.
ls-tag --ls-tag -T [tag/regexp]
search for a tag in the log file
only for distribution directories
ls-version --ls-version [version/regexp]
search for a version in the log file
only for distribution directories
cat-changes --cat-changes [dist|d|links|l]
show the changes-file (for distribution or links)
tail-changes --tail-changes [dist|d|links|l,n]
show the last n lines of the changes-file
(for distribution or links)
commands for the config-file:
show-config --show-config
Print the contents of a valid configuration file to the
screen. You can for example create a configuration file
by supplying --hosts, --user, --distpath, --linkpath and
--localpath on the command-line and additionally
--show-config. The program will then print a generated
configuration-file to the console. If you redirect this
to a file you have your configuration file.
write-config --write-config [filename]
like --show-config but write to a file
show-config-from-log --show-config-from-log
similar to --show-config, but in this case the program
also reads the local log-file to get information on
the remote-host, the remote-user and the remote paths.
write-config-from-log --write-config-from-log [filename]
like --show-config-from-log but write to a file
help options:
-h: this help
--man: show embedded manpage
--summary: give a summary of the script
options to specify remote host and user:
--host -H [remote-host[,remote-host2...]]
a list of remote-hosts separated by comma, spaces, or colon
if this option is not given the script tries to read from
the environment variable "RSYNC_DIST_HOST"
--user -u [remote-user[,remote-user2...]]
user for login on the remote host
if this option is not given the script tries to read from
the environment variable "RSYNC_DIST_USER"
options to specify the ssh command:
--ssh-local [ssh command]
the way ssh from the local host is started can be overridden this way.
--ssh-remote [ssh command]
the way ssh from the remote host is started can be overridden this way.
options to specify directories:
--distpath -p [remote-dist-path]
remote directory where files are disted
if this option is not given the script tries to read from
the environment variable "RSYNC_DIST_PATH"
--linkpath -P [remote link-path]
remote directory where links are created
if this option is not given the script tries to read from
the environment variable "RSYNC_DIST_LINKPATH"
--localpath -l [local-path,local-path2...]
list of files or directories to be distributed
if this option is not given the script tries to read from the
environment variable "RSYNC_DIST_LOCALPATH" Several paths can
be specified with either a comma-separated list or several -l
options. If a localpath contains a single dot like in
"build/./bin", rsync-dist will only create the directory or
directories *after* the dot on the target hosts. In the example
above, the local directory "build/bin" would be installed as
"bin".
--localprefix [prefix]
prepended to all files or directories to be distributed
if this option is not given the script tries to read from
the environment variable "RSYNC_DIST_LOCALPREFIX"
options to specify tags and log-messages:
--message -m {logmessage}
specify a log message
if this option is not given the script tries to read from
the environment variable "RSYNC_DIST_MESSAGE"
if this option is given without being followed by a
message, an empty log-message is used
--automessage
(only for the "add-links" or "change-links" commannds)
generate a message of the style
"link to [tag]" where [tag] is the tag of the
last distributed version. This is an alternative
to the "--message" option
--tag -t [tag]
a tag for the distribution
if this option is not given the script tries to read from
the environment variable "RSYNC_DIST_TAG"
if this option is given without being followed by a
tag-string, an empty tag is used
--autotag (only for the "dist" command)
take the tag from the last distributed version and
increment the number at the end of this tag by one.
This is an alternative to the "--tag" option
options for the management of pre-defined parameters:
--config -c [filename]
read variables from a configuration file. The format
is simple <name>=<value>
Empty lines and lines starting with "#" are ignored.
Spaces around the "=" sign are also ignored. Array values
are specified as comma-separated lists. All variable names
correspond with a command line option and can also be specified
this way.
The following variables are recognized
RSYNC_DIST_HOST
name of the distribution host or hosts.
More than one host can be specified as a
comma-separated list. See also --hosts.
RSYNC_DIST_USER
the username(s) rsync-dist.pl uses to log on to the remote
hosts. See also --user. When several hosts (see above)
are defined, you can define several (possibly different)
users for the hosts. See also --users.
RSYNC_DIST_SSH_LOCAL
specify the local ssh command that is used. See also --ssh-local.
RSYNC_DIST_SSH_REMOTE
specify the remote ssh command that is used. See also --ssh-remote.
RSYNC_DIST_SSH_BACK_TUNNEL
specify the ssh-tunnel port. See also --ssh-back-tunnel.
RSYNC_DIST_PATH
the remote distribution directory. See also --distpath.
RSYNC_DIST_LINKPATH
the remote link directory, see also --linkpath.
RSYNC_DIST_PREFIX_DISTDIR
If empty or '1', prepend the distribution directory to the
link-source path. If this is a non-empty string prepend this
to the link source path. This effects only the connamds
'add-links' and 'change-links'. See also --prefix-distdir.
RSYNC_DIST_LOCALPATH
the local directory or directories. More than one
directory can be specified in a comma-separated list.
See also --localpath.
RSYNC_DIST_LOCALPREFIX
the prefix that is prepended to local paths (see above)
see also --localprefix
RSYNC_DIST_WORLDREADABLE
when set to 1, make all distributed files world-readable
see also --world-readable
RSYNC_DIST_ONE_FILESYSTEM
when set to 1, do not cross filesystem boundaries on the
local host. See also --one-filesystem
RSYNC_DIST_PRESERVE_LINKS
when set to 1, symbolic links are never dereferenced and
always copied as links. See also --preserve-links.
RSYNC_DIST_DEREFERENCE_LINKS
when set to 1, symbolic links always dereferenced. See also
--dereference-links.
RSYNC_DIST_EXCLUDE_LIST
specify a file on the local host that contains files that
are to be excluded. See also exclude-list.
RSYNC_DIST_CHECKSUM
when set to 1, use checksums to detect changes in files.
see also --checksum.
RSYNC_DIST_BRANCH
when this variable is defined, use this branch
for distributing files. See also --branch.
RSYNC_DIST_PARTIAL
when set to 1, make a complete copy of the last version on the
server but distribute only some files from the client
to the server. --localpath may contain file-glob patterns
in this case. See also --partial.
RSYNC_DIST_EDITOR
the default editor to enter options that the used didn't
specify on the command lines. The default is "vi".
See also --editor.
RSYNC_DIST_EDITOR_NO_DEFAULTS
when set to 1, the editor does not show defaults,
when called. See also --no-editor-defaults.
RSYNC_DIST_SHOW_PROGRESS
when set to 1, show progress of rsync on console. See also
--progress.
RSYNC_DIST_TAG
specify a default-tag, may also be empty. In this
case the program does not request a tag if no one
is given on the command line. See also --tag.
RSYNC_DIST_MESSAGE
specify a default log-message, may also be empty. In this
case the program does not request a message if no one
is given on the command line. See also --message.
RSYNC_DIST_FILTER_OUTPUT
when set to 1, output from remote ssh commands
is filtered to make it more human readable. This affects the
commands "change-links", "add-links", and "ls links". See also
--filter-output.
Note that command-line arguments always override
values taken from the config-file.
--env By supplying this option, the program can take all
variables mentioned above (see --config) from the
unix-shell environment.
miscellaneous options:
--branch [branchname]
use the most recent version of <branchname> to make the
hardlink-copy on the server.
--partial make a complete copy of the last version on the
server but distribute only some files from the client
to the server. --localpath may contain file-glob patterns
--filter-output
when this option is given, output from remote ssh commands
is filtered to make it more human readable. This affects the
commands "change-links", "add-links", and "ls links".
--version-file [filename]
when the <dist> command is executed, the name of
the directory that is created on the server is written
to this file.
Note that the filename may be a complete path+filename.
If the path is not absolute, it is assumed to be relative
to localprefix. If localprefix is not specified, it is
assumed to be relative to the current working directory.
Note too, that the file may be created in one of the
directories that is to be distributed. This is done before
the actual transfer of files takes place, so you will
find the generated file on the server too, in this case.
--editor [editor]
specify the interactive editor.
if this option is not given the script tries to read from
the environment variable "RSYNC_DIST_EDITOR", if this
is not set from "EDITOR", if this is not set the
default is "vi"
Note that these environment variables are
even if "--env" (see above) is not given
--no-editor-defaults -N
do not show defaults for the text-entries when the
editor is called
--no-no-editor-defaults
set "--no-editor-defaults" (see above) to false
(use editor defaults). Since this is the default behavior,
this option is only needed in order to override a
different setting taken from a config file
--prefix-distdir
If empty or '1', prepend the distribution directory to the
link-source path. If this is a non-empty string prepend this to
the link source path. This effects only the connamds
'add-links' and 'change-links'.
Together with --last-dist you can specify the "source" part
completely like it is shown here:
rsync-dist.pl --config my_config --prefix-distdir 1
--last-dist change-links idcp*
and here:
rsync-dist.pl --config my_config --prefix-distdir 1
--last-dist change-links idcp1,idcp2
--last-dist -L
append the name of the last distribution that was
made to the "source" part of the add-links or
change-links command
--one-filesystem
do not cross filesystem boundaries on the local host
--preserve-links
never dereference links, just keep them
--dereference-links
always dereference links
--exclude-list [file]
specify a file that contains files to be excluded from transfer
--checksum use checksums instead of date-comparisons when deciding
whether a file should be transferred
--progress use the rsync "progress" option to show the progress
of rsync on screen
--dry-run just show the command that would be executed
--world-readable -w
make all files world-readable
--create_missing_links
for use with command "change-links": don't complain if links
don't exist, instead create them
--ssh-back-tunnel [port]
use an existing ssh-tunnel on remote host in order to connect
back to the local host. This option has only an effect on
the "dist" command.
Such a tunnel can be created by issuing this command
on your local host:
ssh -R <port>:localhost:22 <remote-user>@<remote-host>
This option may also be set by the environment
variable RSYNC_DIST_SSH_BACK_TUNNEL.
--single-host
perform "ls" or "cat-log" or "tail-log" command
only on the first remote host.