Skip to content

Use virtual instances on Linux

A virtual instance is a working tree that the Lore service mounts with FUSE and serves from the store. Cloning one writes no files, a file's content is fetched the first time it's read, and every change is recorded as it's written, so lore status needs no --scan. Reach for one when a repository is too large to write out in full, or when you only touch part of it. This guide assumes you can already clone the repository, and covers making virtual instances, getting them back after the service stops, and moving and removing them. For a step-by-step walk through the edit loop in one, follow Work in a virtual instance on Linux.

Prerequisites

  • Linux 6.8 or later, with /dev/fuse and fusermount3. Most distributions ship fusermount3 in a package named fuse3.
  • The lore CLI on your PATH. See Install the Lore CLI.

Make a virtual instance

  1. Name the build that serves your virtual instances (optional).

    Every command that makes or works in a virtual instance is carried out by the Lore service. Cloning starts the service from the lore you ran when it finds none running. If several builds of lore are on your machine, name the one that serves your virtual instances, so it doesn't depend on which you run first:

    lore service set-executable "$(command -v lore)"
    
  2. Choose where the shared store lives (optional).

    A virtual instance keeps the content it fetches in the shared store for its server, and the service finds its virtual instances through the shared stores when it starts. The first instance cloned from a server creates its store in Lore's data directory, ~/.local/share/lore. To keep the store on another drive, create it there before you clone anything from that server, passing the server's address with no repository path:

    lore shared-store create lore://127.0.0.1:41337 --path /mnt/data/lore
    

    A store created after the first instance becomes the new default, and instances that follow the default then open the new, empty store. See Keep the store on another drive.

  3. Clone with --vfs fuse.

    lore clone lore://127.0.0.1:41337/my-project ~/my-project-fuse --vfs fuse
    

    findmnt ~/my-project-fuse then lists a fuse.lore mount. --vfs default makes the same kind of instance on Linux. A virtual instance always uses the shared store, so it needs no --use-shared-store.

  4. Work in it as in any working tree.

    Edit files with any tool. The mount records each change as it's written, so lore status and lore stage . see it with no --scan and no lore file dirty. Stage, commit, push, sync, and switch branches as usual.

Get your virtual instances back after the service stops

The service holds the mount of every virtual instance it serves. Once it stops, after lore service stop or a restart of the machine, each virtual instance's directory is empty, and a command there reports Repository not found rather than start the service. Start the service to mount every virtual instance it finds through your shared stores again, at the revision each one stood on and with your uncommitted changes in place:

lore service start

Move a virtual instance

Run the move from outside the virtual instance: the service can't move a mount that a shell or a program has as its working directory.

lore --repository ~/my-project-fuse repository instance move ~/work/my-project-fuse

The service mounts the virtual instance at the new path, with its uncommitted changes, and removes the old directory. It creates the directories above the new path that don't exist yet, here ~/work, and removes them again if the move fails. The new path itself must not exist.

Remove a virtual instance

Removing a virtual instance deletes its uncommitted changes, so commit and push what you want to keep first. Run the removal from outside the virtual instance, as for a move:

lore --repository ~/work/my-project-fuse repository instance delete

The service takes the mount down, deregisters the virtual instance, and removes its directory.

Move the external directories

Each virtual instance keeps its Lore directory, and every file written through its mount, in an external directory in ~/.local/share/lore/external. To keep them in another directory on the same volume, move them with the service's own command, which stops the service and starts it again around the move:

lore service set-external-directory ~/work/lore-external

See Move the external directories of virtual instances for the precautions to take first and how to move them back.

Stop the service

cd ~
lore service stop

A stop is refused while a shell or a program is inside a virtual instance. Leave the virtual instance and close the program, or run lore service stop --force, which detaches every mount at once and cuts off the programs inside.

Result

Your virtual instances are mounted while the service runs, and lore status in one lists your changes with no --scan.

See also