Introduction
The FileVault tool (VLT) is a tool developed by Adobe that maps the content of a CRX/CQ instance to your file system. The VLT tool has similar functions as source control system client (such as a Subversion (SVN) client), providing normal check-in, check-out and management operations, as well as configuration options for flexible representation of the project content.
Getting Started with VLT
To start
using VLT, you need to do the following:
- Install VLT, update environment variables, and update global ignored subversion files.
- Set up the CRX/CQ repository (if you have not already done so).
- Check out the CRX/CQ repository.
- Synchronize with the repository.
- Test whether the synchronization worked.
Installing the vlt tool
To use
the VLT tool, you first need to install it. It is not installed by default
and is an additional tool available in the /opt folder of your CQ
instance. In addition, you need to set your system's environment variable.
After you
have installed it you need to update global ignored subversion files. Edit your
svn settings and add the following:
[miscellany]
### Set global-ignores to a set
of whitespace-delimited globs
### which Subversion will ignore
in its 'status' output, and
### while importing or adding
files and directories.
global-ignores = .vlt
Configuring the End of Line Character
VLT
automatically handles End Of Line (EOF) according to the following rules:
- lines of files checked out on Windows end with a CRLF
- lines of files checked out on Unices end with a LF
- lines of files commited to the repository end with a LF
Note:-
Systems based on ASCII or a compatible character set use either LF (Line feed, '\n', 0x0A, 10 in decimal) or CR (Carriage
return, '\r', 0x0D,
13 in decimal) individually, or CR
followed by LF (CR+LF,
'\r\n', 0x0D0A).
These characters are based on printer commands: The line feed indicated
that one line of paper should feed out of the printer thus instructed the
printer to advance the paper one line, and a carriage return indicated
that the printer carriage should return to the beginning of the current line.
Some rare systems, such as QNX before version 4, used the ASCII RS (record separator, 0x1E, 30 in decimal) character as the newline
character.
Setting up the CRX/CQ repository
Install CRX or install CQ and start the instance.
A CRX
quickstart jar file includes a JCR-compliant repository and Apache Sling, which
is a web framework for developing web applications on Java.
The first
time you start the jar file, it creates an entire JCR-compliant repository in
the background, which may take several minutes. After the first time, startup
is much quicker as the repository has already been created
Checking out the repository
Check out
the repository using the source control system. In svn, for example, type the
following (substituting the URI and path with your repository):
| svn co http://svn.server.com/repos/myproject |
Synchronizing with the repository
You need
to synchronize filevault with the repository. To do this:
- In the command line, navigate to content/jcr_root.
- Check out the repository by typing the following (substituting your port number for 4502 and your admin passwords):
| vlt --credentials admin:admin co --force http://localhost:4502/crx |
Note
The credentials have to be specified only once upon your initial checkout. They will then be stored in your home directory inside .vault/auth.xml.
After you
have checked out the repository and synchronized it, you should test to make
sure everything functions properly. An easy way to do this is to edit a .jsp
file and see whether your changes are reflected after committing the changes.
- Navigate to .../jcr_content/libs/foundation/components/text.
- Edit something in text.jsp.
- See the modified files by typing vlt st
- See the changes by typing vlt diff text.jsp
- Commit the changes: vlt ci test.jsp.
- Reload a page containing a text component and see whether your changes are there.
VLT Commands
The
following table describes all available VLT commands. See the individual
commands for detailed information on syntax, available options, and examples.
Abbreviated
Command
|
Description
|
|
export
|
Exports
from a JCR repository (vault file system) to the local file system without
control files.
|
|
import
|
Imports
a local file system to a JCR repository (vault file system).
|
|
checkout
|
co
|
Checks
out a Vault file system. Use this for an initial JCR repository to the local
file system. (Note: You must first check out the repository in
subversion.)
|
analyze
|
Analyzes
packages.
|
|
status
|
st
|
Prints
the status of working copy files and directories.
|
update
|
up
|
Imports
changes from the repository into the working copy.
|
info
|
Displays
information about a local file.
|
|
commit
|
ci
|
Sends
changes from your working copy to the repository.
|
revert
|
rev
|
Restores
the working copy file to its original state and undoes most local edits.
|
resolved
|
res
|
Removes
conflicted state on working copy files or directories.
|
propget
|
pg
|
Prints
the value of a property on files or directories.
|
proplist
|
pl
|
Prints
the properties on files or directories.
|
propset
|
ps
|
Sets
the value of a property on files or directories.
|
add
|
Puts
files and directories under version control.
|
|
delete
|
del or
rm
|
Removes
files and directories from version control.
|
diff
|
di
|
Displays
the differences between two paths.
|
console
|
Runs an
interactive console.
|
|
rcp
|
Copies
a node tree from one remote repository to another.
|
|
sync
|
Allows
to control the vault sync service.
|
Export
Exports the Vault filesystem mounted at <uri> to the local filesystem at <local-path>. An optional <jcr-path> can be specified in order to export just a sub-tree.Syntax
export -v|-t <arg>|-p
<uri> <jcr-path> <local-path> |
Options
verbose output
|
|
-t (--type) <arg>
|
specifies the export type, either platform or jar.
|
-p (--prune-missing)
|
specifies if missing local files should be deleted
|
<uri>
|
mountpoint uri
|
<jcrPath>
|
JCR path
|
<localPath>
|
local path
|
Examples
vlt
export http://localhost:4502/crx /apps/geometrixx myproject |
Import
Imports the local file system (starting at <local-path> to the vault file system at <uri>. You can specify a <jcr-path>as import root. If --sync is specified, the imported files are automatically put under vault control.Syntax
import -v|-s <uri>
<local-path> <jcr-path> |
Options
verbose output
|
|
-s (-- sync)
|
puts the local files under vault control
|
<uri>
|
mountpoint uri
|
<jcrPath>
|
JCR path
|
<localPath>
|
local path
|
Examples
vlt import http://localhost:4502/crx . / |
Checkout (co)
Performs an initial check out from a JCR repository to the local filesystem starting at <uri> to the local filesystem at <local-path>. You can also add a <jcrPath> argument to check out a sub-directory of the remote tree. Workspace filters can be specified that are copied into the META-INF directory.Syntax
checkout
--force|-v|-q|-f <file> <uri> <jcrPath>
<localPath> |
Options
forces checkout to overwrite local files if they already
exist
|
|
-v (--verbose)
|
verbose output
|
-q (--quiet)
|
prints as little as possible
|
-f (--filter) <file>
|
specifies auto filters if none are defined
|
<uri>
|
mountpoint uri
|
<jcrPath>
|
(optional) remote path
|
<localPath>
|
(optional) local path
|
Examples
Using JCR Remoting:vlt --credentials admin:admin co http://localhost:8080/crx/server/crx.default/jcr_root/ |
vlt --credentials admin:admin co
http://localhost:8080/crx/server/-/jcr_root/ |
vlt --credentials admin:admin co http://localhost:8080/crx |
Analyze
Analyzes packages.Syntax
analyze
-l <format>|-v|-q <localPaths1> [<localPaths2> ...] |
Options
printf format for hotfix links (name,id), for example
[CQ520_HF_%s|%s] |
|
-v (--verbose)
|
verbose output
|
-q (--quiet)
|
prints as little as possible
|
<localPaths> [<localPaths> ...]
|
local path
|
Status
Prints the status of working copy files and directories.If --show-update is specified, each file is checked against the remote version. The second letter then specifies what action would be performed by an update operation.
Syntax
status
-v|-q|-u|-N <file1> [<file2> ...] |
Options
verbose output
|
|
-q (--quiet)
|
prints as little as possible
|
-u (--show-update)
|
displays update information
|
-N (--non-recursive)
|
operates on a single directory
|
<file> [<file> ...]
|
file or directory to display the status
|
Update
Copies changes from the repository into the working copy.Syntax
update
-v|-q|--force|-N <file1> [<file2> ...] |
Options
verbose output
|
|
-q (--quiet)
|
prints as little as possible
|
--force
|
forces the overwrite of local files
|
-N (--non-recursive)
|
operates on a single directory
|
<file> [<file> ...]
|
file or directory to update
|
Info
Displays information about a local file.Syntax
info
-v|-q|-R <file1> [<file2> ...] |
Options
verbose output
|
|
-q (--quiet)
|
prints as little as possible
|
-R (--recursive)
|
operates recursive
|
<file> [<file> ...]
|
file or directory to display info
|
Commit
Sends changes from your working copy to the repository.Syntax
commit
-v|-q|--force|-N <file1> [<file2> ...] |
Options
verbose output
|
|
-q (--quiet)
|
prints as little as possible
|
--force
|
forces committing even if the remote copy is modified
|
-N (--non-recursive)
|
operates on a single directory
|
<file> [<file> ...]
|
file or directory to commit
|
Revert
Restores working copy file to original state and undoes most local edits.Syntax
revert
-q|-R <file1> [<file2> ...] |
Options
prints as little as possible
|
|
-R (--recursive)
|
descends recursively
|
<file> [<file> ...]
|
file or directory to commit
|
Add
Puts files and directories under version control, scheduling them for addition to repository. They will be added on next commit.Syntax
add
-v|-q|-N|--force <file1> [<file2> ...] |
Options
verbose output
|
|
-q (--quiet)
|
prints as little as possible
|
-N (--non-recursive)
|
operates on a single directory
|
--force
|
forces the operation to run
|
<file> [<file> ...]
|
local file or directory to add
|
Delete
Removes files and directories from version control.Syntax
delete
-v|-q|--force <file1> [<file2> ...] |
Options
verbose output
|
|
-q (--quiet)
|
prints as little as possible
|
--force
|
forces the operation to run
|
<file> [<file> ...]
|
local file or directory to delete
|
Diff
Displays the differences between two paths.Syntax
diff
-N <file1>
[<file2> ...] |
Options
operates on a single directory
|
|
<file> [<file> ...]
|
file or directory to display the differences from
|
Console
Runs an interactive console.Syntax
console
-F <file> |
Options
specifies the console settings file. The default file is console.properties.
|
Rcp
Copies a node tree from one remote repository to another. <src> points to the source node and <dst> specifies the destination path, where the parent node must exist. Rcp processes the nodes by streaming the data.Syntax
rcp
-q|-r|-b <size>|-t
<seconds>|-u|-n|-e <arg1> [<arg2> ...] <src>
<dst> |
Options
Prints as little as possible.
|
|
-r (--recursive)
|
Descends recursively.
|
-b (--batchSize) <size>
|
Number of nodes to be processed before
an intermediate save.
|
-t (--throttle) <seconds>
|
Number of seconds to wait after
an intermediate save. |
-u (--update)
|
Overwrite/delete existing nodes.
|
-n (--newer)
|
Respect lastModified properties for update.
|
-e (--exclude) <arg> [<arg> ...]
|
Regexp of excluded source paths.
|
<src>
|
The repository address of the source tree.
|
<dst>
|
The repository address of the destination node.
|
Examples
vlt rcp
http://localhost:4502/crx/-/jcr:root/content http://admin:admin@localhost:4503/crx/-/jcr:root/content_copy
Sync
Allows to control the vault sync service. Without any arguments this command tries to put the current working directory under sync control. If executed within a vlt checkout, it uses the respective filter and host to configure the synchronization. If executed outside of a vlt checkout, it registers the current folder for synchronization only if the directory is empty.Syntax
sync
-v|--force|-u
<uri> <command> <localPath> |
Options
verbose output.
|
|
--force
|
force certain commands to execute.
|
-u (--uri) <uri>
|
specifies the URI of the sync host.
|
<command>
|
sync command to execute.
|
<localPath>
|
local folder to sync.
|
Status Codes
The status codes used by VLT are:- ' ' no modifications
- 'A' Added
- 'C' Conflicted
- 'D' Deleted
- 'I' Ignored
- 'M' Modified
- 'R' Replaced
- '?' item is not under version control
- '!' item is missing (removed by non-svn command) or incomplete
- '~' versioned item obstructed by some item of a different kind
Setting up FileVault sync
This
section describes the new synchronization feature shipped with FileVault tool
(vlt) since the version 2.4.24.
The vault
sync service is used to synchronize repository content with a local filesystem
representation and vice versa. This is achieved by installing an OSGi service
that will listen for repository changes and will scan the filesystem content
periodically. It uses the same serialization format as vault for mapping the
repository content to disk.
Installing the service using vlt
The vlt
sync install command can be used to install the vault sync service bundle and
configuration automatically.
The
bundle is installed below /libs/crx/vault/install and the config node is
created at /libs/crx/vault/com.day.jcr.sync.impl.VaultSyncServiceImpl.
Initially the service is enabled but no sync roots are configured.
The
following example installs the sync service to the CRX instance accessible by
the given uri.
Note
The vault
sync service is a development tool and it is highly discouraged to use it on a
productive system. Also note that the service can only sync with the local
filesystem and cannot be used for remote development.
|
