How to Use the VLT Tool how-to-use-the-vlt-tool

The Jackrabbit FileVault tool (VLT) is a tool developed by The Apache Foundation that maps the content of a Jackrabbit/AEM 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, and configuration options for flexible representation of the project content.

You run the VLT tool from the command line. This document describes how to use the tool, including how to get started and get help, and a list of all commands and available options.

Concepts and Architecture concepts-and-architecture

See the Filevault Overview and Vault FS page from the official Apache Jackrabbit Filevault documentation for a thorough overview of the concepts and strucure of the Filevault tool.

Getting Started with VLT getting-started-with-vlt

To start using VLT, you need to do the following:

Installing the VLT Tool 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.

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 configuring-the-end-of-line-character

VLT automatically handles End Of Line (EOF) according to the following rules:

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 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 synchronizing-with-the-repository

You need to synchronize filevault with the repository. To do this:

Testing Whether the Synchronization Worked 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:

Getting Help with the VLT Tool 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 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 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 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 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:

Using VLT 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 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.

VLT Commands vlt-commands

The following table describes all available VLT commands. See the individual commands for detailed information on syntax, available options, and examples.

Export 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 syntax

export -v|-t <arg>|-p <uri> <jcr-path> <local-path>

Options options

Examples examples

vlt export http://localhost:4502/crx /apps/geometrixx myproject

Import 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 syntax-1

import -v|-s <uri> <local-path> <jcr-path>

Options options-1

Examples examples-1

vlt import http://localhost:4502/crx . /

Checkout (co) 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 syntax-2

checkout --force|-v|-q|-f <file> <uri> <jcrPath> <localPath>

Options options-2

Examples examples-2

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 analyze

Analyzes packages.

Syntax syntax-3

analyze -l <format>|-v|-q <localPaths1> [<localPaths2> ...]

Options options-3

Status 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 syntax-4

status -v|-q|-u|-N <file1> [<file2> ...]

Options options-4

Update update

Copies changes from the repository into the working copy.

Syntax syntax-5

update -v|-q|--force|-N <file1> [<file2> ...]

Options options-5

Info info

Displays information about a local file.

Syntax syntax-6

info -v|-q|-R <file1> [<file2> ...]

Options options-6

Commit commit

Sends changes from your working copy to the repository.

Syntax syntax-7

commit -v|-q|--force|-N <file1> [<file2> ...]

Options options-7

Revert revert

Restores working copy file to original state and undoes most local edits.

Syntax syntax-8

revert -q|-R <file1> [<file2> ...]

Options options-8

Resolved resolved

Removes conflicted state on working copy files or directories.

Syntax syntax-9

resolved -q|-R|--force <file1> [<file2> ...]

Options options-9

Propget propget

Prints the value of a property on files or directories.

Syntax syntax-10

propget -q|-R <propname> <file1> [<file2> ...]

Options options-10

Proplist proplist

Prints the properties on files or directories.

Syntax syntax-11

proplist -q|-R <file1> [<file2> ...]

Options options-11

Propset propset

Sets the value of a property on files or directories.

Syntax syntax-12

propset -q|-R <propname> <propval> <file1> [<file2> ...]

Options options-12

Add add

Puts files and directories under version control, scheduling them for addition to repository. They will be added on next commit.

Syntax syntax-13

add -v|-q|-N|--force <file1> [<file2> ...]

Options options-13

Delete delete

Removes files and directories from version control.

Syntax syntax-14

delete -v|-q|--force <file1> [<file2> ...]

Options options-14

Diff diff

Displays the differences between two paths.

Syntax syntax-15

diff -N <file1> [<file2> ...]

Options options-15

Console console

Runs an interactive console.

Syntax syntax-16

console -F <file>

Options options-16

Rcp 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 syntax-17

rcp -q|-r|-b <size>|-t <seconds>|-u|-n|-e <arg1> [<arg2> ...] <src> <dst>

Options options-17

Examples examples-3

vlt rcp http://localhost:4502/crx/-/jcr:root/content  https://admin:admin@localhost:4503/crx/-/jcr:root/content_copy

Sync 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 syntax-18

sync -v|--force|-u <uri> <command> <localPath>

Options options-18

Status Codes status-codes

The status codes used by VLT are:

Setting Up FileVault Sync 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 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 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.

Adding a sync folder 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

Removing a sync folder 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 configuring-synchronization

Service configuration service-configuration

Once the service is running it can be configured with the following parameters:

Sync folder configuration sync-folder-configuration

Each sync folder stores configuration and status in three files:

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:

sync-log Defines the log filename. By default, the value is .vlt-sync.log

Using VLT sync for development using-vlt-sync-for-development

To setup a development environment based on a sync folder proceed as follows:

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.