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/fuseandfusermount3. Most distributions shipfusermount3in a package namedfuse3. - The
loreCLI on your PATH. See Install the Lore CLI.
Make a virtual instance¶
-
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
loreyou ran when it finds none running. If several builds ofloreare on your machine, name the one that serves your virtual instances, so it doesn't depend on which you run first: -
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: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.
-
Clone with
--vfs fuse.findmnt ~/my-project-fusethen lists afuse.loremount.--vfs defaultmakes the same kind of instance on Linux. A virtual instance always uses the shared store, so it needs no--use-shared-store. -
Work in it as in any working tree.
Edit files with any tool. The mount records each change as it's written, so
lore statusandlore stage .see it with no--scanand nolore 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:
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.
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:
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:
See Move the external directories of virtual instances for the precautions to take first and how to move them back.
Stop the service¶
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¶
- Work in a virtual instance on Linux — the edit loop step by step, and what to do when cloning fails.
[service]table in the CLI configuration reference — which build is started as the service.lore clonein the CLI command reference —--vfsand the other flags oflore clone.- Run parallel instances over a shared store — shared stores and the instances over them.