Usage

To start the server, run:

docker run -v /path/to/data:/data -p 9090:9090 robrt/jolt-cache -i

To push a tree to the server, run:

fstree write-tree-push --remote jolt://localhost:9090 /path/to/data

The steps above can be split into two separate commands:

fstree write-tree /path/to/data
fstree push --remote jolt://localhost:9090 <digest>

To push a tree to a standard HTTP server, run:

fstree write-tree-push --remote http://localhost:8080 /path/to/data'

To pull a tree from the server, run:

fstree pull-checkout --remote jolt://localhost:9090 <digest> /path/to/data

The steps above can be split into two separate commands:

fstree pull --remote jolt://localhost:9090 <digest>
fstree checkout <digest> /path/to/data

To pull a tree from a standard HTTP server, run:

fstree pull-checkout --remote http://localhost:8080 <digest> /path/to/data

To list the contents of a tree, run:

fstree ls-tree <digest>

To print the content of a file in the cache, or the entries of a tree, run:

fstree cat-file <digest>

Configuration

Configuration can be passed as command line arguments or environment variables.

The following environment variables are supported:

• FSTREE_CACHE: The directory where the local object cache is stored. Defaults to ~/.cache/fstree on Linux and macOS and ~/AppData/Local/fstree on Windows.

• FSTREE_IGNORE: The relative path to the ignore file. Defaults to .fstreeignore in the root of the tree.

• FSTREE_IGNORE_PATTERN: Patterns to ignore in addition to those of the ignore file, one per line, with the syntax of the lines of the ignore file. They come after those of the ignore file, so they take precedence. They are not stored in the tree, so the same patterns must be given when it is checked out. Also given as --ignore-pattern, once for each pattern.

• FSTREE_PERMISSIONS: How permissions are recorded in trees and restored at checkout, exact or git. Defaults to exact, which records and restores all permission bits. With git, only whether a file is executable is recorded, as git does, so trees written from checkouts made with different umasks are the same. Files are then checked out with 0666 or 0777 and directories with 0777, less the umask. Applies to POSIX systems only. Also given as --permissions.

• FSTREE_REMOTE: The remote address of the server to connect to. Defaults to jolt://localhost:9090. Use tls:// for a gRPC server with TLS, and https:// for an HTTP server with TLS.

• FSTREE_CONNECT_TIMEOUT: Seconds to wait for the connection to a gRPC server before giving up. Defaults to 60.

• FSTREE_THREADS: The number of threads to use for parallel operations. Defaults to the number of CPU cores.

Servers that require authentication are configured with the same variables as Jolt:

• JOLT_CACHE_TOKEN: Token that authenticates the client with the server. It is only sent over TLS, to tls:// and https:// remotes.

• JOLT_CA_CERT: PEM file with the certificates of the authorities that the certificate of the server is verified with, such as a private authority.

• JOLT_ALLOW_INSECURE_TOKEN: Set to true to send the token without TLS.

The following command line arguments are supported:

• --cache: See FSTREE_CACHE.

• --ignore: See FSTREE_IGNORE.

• --remote: See FSTREE_REMOTE.

• --threads: See FSTREE_THREADS.

Building

The project can be built using CMake, but developers typically use Jolt as a higher level orchestrator. To build the project using Jolt, run:

pip install jolt
jolt build fstree