Installing the VLT Tool
To use the VLT tool, you first need to install it. It is not installed by default as it is an additional tool. In addition, you need to set your system’s environment variable.
-
Download the FileVault archive file from the Maven artifact repository.
NOTE
The source of the VLT tool is available on GitHub.1. Extract the archive.
-
Add
<archive-dir>/vault-cli-<version>/bin
to your environmentPATH
so that the command filesvlt
orvlt.bat
are accessed as appropriate. For example:<aem-installation-dir>/crx-quickstart/opt/helpers/vault-cli-3.1.16/bin>
-
Open a command line shell and execute
vlt --help
. Make sure the output is similar to the following help screen:vlt --help ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Jackrabbit FileVault [version 3.1.16] Copyright 2013 by Apache Software Foundation. See LICENSE.txt for more information. ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Usage: vlt [options] <command> [arg1 [arg2 [arg3] ..]] ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Global options: -Xjcrlog <arg> Extended JcrLog options (omit argument for help) -Xdavex <arg> Extended JCR remoting options (omit argument for help) --credentials <arg> The default credentials to use --update-credentials if present the credentials-to-host list is updated in the ~/.vault/auth.xml --config <arg> The JcrFs config to use -v (--verbose) verbose output -q (--quiet) print as little as possible --version print the version information and exit --log-level <level> the log4j log level -h (--help) <command> print this help
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 Linux/Unix end with a
LF
- lines of files commited to the repository end with a
LF
To guarantee that VLT and SVN configuration match, you should set up the svn:eol-style
property to native
for the extension of the files stored in the repository. Edit your svn settings and add the following:
[auto-props]
*.css = svn:eol-style=native
*.cnd = svn:eol-style=native
*.java = svn:eol-style=native
*.js = svn:eol-style=native
*.json = svn:eol-style=native
*.xjson = svn:eol-style=native
*.jsp = svn:eol-style=native
*.txt = svn:eol-style=native
*.html = svn:eol-style=native
*.xml = svn:eol-style=native
*.properties = svn:eol-style=native
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 https://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
.
Testing Whether the Synchronization Worked
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.
To test the synchronization:
- 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.
Getting Help with the VLT Tool
After installing the VLT tool, you can access its Help file from the command line:
vlt --help
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Jackrabbit FileVault [version 3.1.16] Copyright 2013 by Apache Software Foundation. See LICENSE.txt for more information.
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Usage:
vlt [options] <command> [arg1 [arg2 [arg3] ..]]
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Global options:
-Xjcrlog <arg> Extended JcrLog options (omit argument for help)
-Xdavex <arg> Extended JCR remoting options (omit argument for help)
--credentials <arg> The default credentials to use
--update-credentials if present the credentials-to-host list is updated in the ~/.vault/auth.xml
--config <arg> The JcrFs config to use
-v (--verbose) verbose output
-q (--quiet) print as little as possible
--version print the version information and exit
--log-level <level> the log4j log level
-h (--help) <command> print this help
Commands:
export Export the Vault filesystem
import Import a Vault filesystem
checkout (co) Checkout a Vault file system
status (st) Print the status of working copy files and directories.
update (up) Bring changes from the repository into the working copy.
info Displays information about a local file.
commit (ci) Send changes from your working copy to the repository.
revert (rev) Restore pristine working copy file (undo most local edits).
resolved (res) Remove 'conflicted' state on working copy files or directories.
propget (pg) Print the value of a property on files or directories.
proplist (pl) Print the properties on files or directories.
propset (ps) Set the value of a property on files or directories.
add Put files and directories under version control.
delete (del,rm) Remove files and directories from version control.
diff (di) Display the differences between two paths.
rcp Remote copy of repository content.
sync Control vault sync service
console Run an interactive console
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
For help on a particular command, type the help command followed by the name of the command. For example:
vlt --help export
Usage:
export -v|-t <arg>|-p <uri> <jcr-path> <local-path>
Description:
Export the Vault filesystem mounted at <uri> to the local filesystem at <local-path>. An optional <jcr-path> can be specified to export just a sub tree.
Example:
vlt export http://localhost:4502/crx /apps/geometrixx myproject
Options:
-v (--verbose) 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
<jcr-path> the jcr path
<local-path> the local path
Common Tasks Performed in VLT
The following are some common tasks performed in VLT. For detailed information on each command see the individual commands.
Checking Out a Subtree
If you only want to check out a subtree of the repository for example, /apps/geometrixx
, you can do so by typing the following:
vlt co http://localhost:4502/crx/-/jcr:root/apps/geometrixx geo
Doing this creates a new export root geo
with a META-INF
and jcr_root
directory and puts all files below /apps/geometrixx
in geo/jcr_root
.
Performing a Filtered Checkout
If you have an existing workspace filter and you want to use it for checkout, you can either first create the META-INF/vault
directory and place the filter there, or specify it on the command line as follows:
$ vlt co --filter filter.xml http://localhost:4502/crx/-/jcr:root geo
An example filter:
<?xml version="1.0" encoding="UTF-8"?>
<workspaceFilter version="1.0">
<filter root="/etc/designs/geometrixx" />
<filter root="/apps/geometrixx"/>
</workspaceFilter>
Using Import/Export Instead of .vlt Control
You can import and export content between a JCR repository and the local file system without using control files.
To import and export content without using .vlt
control:
-
Initially set up the repository:
$ cd /projects $ svn mkdir https://svn.server.com/repos/myproject $ svn co https://svn.server.com/repos/myproject $ vlt export -v http://localhost:4502/crx /apps/geometrixx geometrixx $ cd geometrixx/ $ svn add META-INF/ jcr_root/ $ svn ci
-
Change the remote copy and update JCR:
$ cd /projects/geometrixx $ vlt -v import http://localhost:4502/crx . /
-
Change the remote copy and update the file server:
$ cd /projects/geometrixx $ vlt export -v http://localhost:4502/crx /apps/geometrixx . $ svn st M META-INF/vault/properties.xml M jcr_root/apps/geometrixx/components/contentpage/.content.xml $ svn ci
Using VLT
To issue commands in VLT, type the following at the command line:
vlt [options] <command> [arg1 [arg2 [arg3] ..]]
Options and commands are described in detail in the following sections.
VLT Global Options
The following is a list of VLT options, which are available for all commands. See the individual commands for information on additional available options.
Option | Description |
-Xjcrlog <arg> | Extended JcrLog options |
-Xdavex <arg> | Extended JCR remoting options |
--credentials <arg> | The default credentials to use |
--config <arg> | The JcrFs config to use |
-v (--verbose) | verbose output |
-q (--quiet) | print as little as possible |
--version | Prints the version information and exits VLT |
--log-level <level> | Indicates the log level, for example, the log4j log level. |
-h (--help) <command> | Prints help for that particular command |
VLT Commands
The following table describes all available VLT commands. See the individual commands for detailed information on syntax, available options, and examples.
Command | 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: 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 | Lets you 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 to export just a sub-tree.
Syntax
export -v|-t <arg>|-p <uri> <jcr-path> <local-path>
Options
-v (--verbose) | 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
-v (--verbose) | 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
--force | 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/
With the default workspace:
vlt --credentials admin:admin co http://localhost:8080/crx/server/-/jcr_root/
If URI is incomplete, it will be expanded:
vlt --credentials admin:admin co http://localhost:8080/crx
Analyze
Analyzes packages.
Syntax
analyze -l <format>|-v|-q <localPaths1> [<localPaths2> ...]
Options
-l (--linkFormat) <format> | printf format for hotfix links (name,id), for example, `[CQ520_HF_%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
-v (--verbose) | 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
-v (--verbose) | 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
-v (--verbose) | 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
-v (--verbose) | 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
-q (--quiet) | prints as little as possible |
-R (--recursive) | descends recursively |
<file> [<file> ...] | file or directory to commit |
Resolved
Removes conflicted state on working copy files or directories.
Syntax
resolved -q|-R|--force <file1> [<file2> ...]
Options
-q (--quiet) | prints as little as possible |
-R (--recursive) | descends recursively |
--force | resolves, even if there are conflict markers |
<file> [<file> ...] | file or directory to resolve |
Propget
Prints the value of a property on files or directories.
Syntax
propget -q|-R <propname> <file1> [<file2> ...]
Options
-q (--quiet) | prints as little as possible |
-R (--recursive) | descends recursively |
<propname> | the property name |
<file> [<file> ...] | file or directory to get the property from |
Proplist
Prints the properties on files or directories.
Syntax
proplist -q|-R <file1> [<file2> ...]
Options
-q (--quiet) | prints as little as possible |
-R (--recursive) | descends recursively |
<file> [<file> ...] | file or directory to list the properties from |
Propset
Sets the value of a property on files or directories.
vlt:mime-type
Syntax
propset -q|-R <propname> <propval> <file1> [<file2> ...]
Options
-q (--quiet) | prints as little as possible |
-R (--recursive) | descends recursively |
<propname> | the property name |
<propval> | the property value |
<file> [<file> ...] | file or directory to set the property to |
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
-v (--verbose) | 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
-v (--verbose) | 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
-N (--non-recursive) | 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
-F (--console-settings) <file> | 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
-q (--quiet) | 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 https://admin:admin@localhost:4503/crx/-/jcr:root/content_copy
--exclude
options need to be followed by another option before the <src>
and <dst>
arguments. For example:vlt rcp -e ".*\.txt" -r
Sync
Lets you control the vault sync service. Without any arguments this command tries to put the current working directory under sync control. If run within a vlt checkout, it uses the respective filter and host to configure the synchronization. If run 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
-v (--verbose) | 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
The vault sync service is used to synchronize repository content with a local filesystem representation and conversely. 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.
$ vlt --credentials admin:admin sync --uri http://localhost:4502/crx install
Displaying the service status
The status
command can be used to display information about the running sync service. ``
$ vlt sync status --uri http://localhost:4502/crx
Connecting via JCR remoting to http://localhost:4502/crx/server
Listing sync status for http://localhost:4502/crx/server/-/jcr:root
- Sync service is enabled.
- No sync directories configured.
status
command does not fetch any live data from the service but rather reads the configuration at /libs/crx/vault/com.day.jcr.sync.impl.VaultSyncServiceImpl
.Adding a sync folder
The register
command is used to add a folder to synchronize to the configuration.
$ vlt sync register
Connecting via JCR remoting to http://localhost:4502/crx/server
Added new sync directory: /tmp/workspace/vltsync/jcr_root
register
command does not trigger a synchronization until you configure the sync-once
configuration.Removing a sync folder
The unregister
command is used to remove a folder to synchronize from the configuration.
$ vlt sync unregister
Connecting via JCR remoting to http://localhost:4502/crx/server
Removed sync directory: /tmp/workspace/vltsync/jcr_root
Configuring synchronization
Service configuration
Once the service is running it can be configured with the following parameters:
-
vault.sync.syncroots
: One or many local filesystem paths that define the sync roots. -
vault.sync.fscheckinterval
: Frequency (in seconds) of which the filesystem should be scanned for changes. Default is 5 seconds. -
vault.sync.enabled
: General flag that enables/disables the service.
sling:OsgiConfig
node (with the name com.day.jcr.sync.impl.VaultSyncServiceImpl
) in the repository.Sync folder configuration
Each sync folder stores configuration and status in three files:
-
.vlt-sync-config.properties
: configuration file. -
.vlt-sync.log
: log file that contains information about the operations performed during syncing. -
.vlt-sync-filter.xml
: filters that define what portions of the repository are synced. The format of this file is decribed by the Performing a filtered checkout section.
The .vlt-sync-config.properties
file lets you configure the following properties:
disabled Turns the synchronization on or off. By default this parameter is set to false to allow the synchronization.
sync-once If non empty the next scan will synchronize the folder in the given direction, then the parameter will be cleared. Two values are supported:
JCR2FS
: exports all content in the JCR repository and writes to the local disk.FS2JCR
: imports all content from the disk into the JCR repository.
sync-log Defines the log filename. By default, the value is .vlt-sync.log
Using VLT sync for development
To setup a development environment based on a sync folder proceed as follows:
-
Checkout your repository with the vlt command line:
$ vlt --credentials admin:admin co --force http://localhost:4502/crx dev
NOTE
You can use filters to only checkout the appropriate paths. See the Performing a filtered checkout section for information. -
Go to the root folder of your working copy:
$ cd dev/jcr_root/
-
Install the sync service to your repository:
$ vlt sync install Connecting via JCR remoting to http://localhost:4502/crx/server Preparing to install vault-sync-2.4.24.jar... Updated bundle: vault-sync-2.4.24.jar Created new config at /libs/crx/vault/config/com.day.jcr.sync.impl.VaultSyncServiceImpl
-
Initialize the sync service:
$ vlt sync Connecting via JCR remoting to http://localhost:4502/crx/server Starting initialization of sync service in existing vlt checkout /Users/colligno/Applications/cq5/vltsync/sandbox/dev/jcr_root for http://localhost:4502/crx/server/-/jcr:root Added new sync directory: /Users/trushton/Applications/aem/vltsync/sandbox/dev/jcr_root The directory /Users/trushton/Applications/aem/vltsync/sandbox/dev/jcr_root is now enabled for syncing. You might perform a 'sync-once' by setting the appropriate flag in the /Users/trushton/Applications/aem/vltsync/sandbox/dev/jcr_root/.vlt-sync-config.properties file.
-
Edit the
.vlt-sync-config.properties
hidden file and configure sync to synchronize the content of your repository:sync-once=JCR2FS
NOTE
This step downloads the whole repository according to your filter configuration. -
Check the log file
.vlt-sync.log
to see the progress:*** 30.04.2017 14:39:10 A file:///Users/trushton/Applications/aem/vltsync/sandbox/dev/jcr_root/apps/geometrixx-outdoors/src/core/src/main/java/info/geometrixx/outdoors/ 30.04.2017 14:39:10 A file:///Users/trushton/Applications/aem/vltsync/sandbox/dev/jcr_root/apps/geometrixx-outdoors/src/core/src/main/java/info/geometrixx/outdoors/core/ 30.04.2017 14:39:10 A file:///Users/trushton/Applications/aem/vltsync/sandbox/dev/jcr_root/apps/geometrixx-outdoors/src/core/src/main/java/info/geometrixx/outdoors/core/product/ 30.04.2017 14:39:10 A file:///Users/trushton/Applications/aem/vltsync/sandbox/dev/jcr_root/apps/geometrixx-outdoors/src/core/src/main/java/info/geometrixx/outdoors/core/product/GeoProduct.java ***
Your local folder is now synchronized with the repository. The synchronization is bi-directionnal so modification from the repository will be applied to you local sync folder and conversely.
Experience Manager
B2B Reimagined: Transforming Go-to-Market Strategies for Profitable Growth
B2B brands are facing a digital revolution. Buyers expect hyper-relevant content and self-service, while internally AI is transforming...
Wed, Mar 19, 1:00 PM PDT (8:00 PM UTC)
The True Cost of a Failed Implementation
A failed implementation isn’t just an inconvenience — it costs real revenue. Poor execution and misaligned tools disrupt pipelines,...
Wed, Mar 19, 2:00 PM PDT (9:00 PM UTC)
Connect with Experience League at Summit!
Get front-row access to top sessions, hands-on activities, and networking—wherever you are!
Learn more