Edit files in a checkout¶
Edit photos in Lightroom or another tool, then save the changes as new versions
in Fotobank. A checkout is a tracked working folder containing ordinary
writable copies. Editing those copies leaves stored versions unchanged until
you explicitly run checkout commit.
The workflow is: choose photos, create the folder, edit, wait for Fotobank to detect settled changes, then inspect and commit them. Keep the daemon running while you edit so it can scan the folder. Conflicts are reported instead of overwriting a newer stored version.
Estimate the copy¶
Every checkout command uses the daemon, starting it when needed. Run these commands on the server host under the same OS account, with the same stub-mode configuration and application version. They use the local operator connection, not the photo listener, and never open a second vault.
To choose individual photos, use media list --json or media search --json,
then inspect each with media show <media-uuid> --json. Pass its id to
--asset. See finding photos for filters
and pagination.
Select photos, albums, capture years, or the complete visible library. The CLI calls a photo an asset:
fotobank checkout estimate --year 2025
fotobank checkout estimate --year 2023:2025
fotobank checkout estimate --album <album-uuid>
fotobank checkout estimate --asset <asset-uuid>
fotobank checkout estimate --all
fotobank checkout estimate --year 2025 --json
Year ranges include both end years. Selectors are repeatable and may be combined. Hidden photos are excluded. An all-library checkout still requires an explicit byte limit at creation so it cannot silently create a second full archive copy.
Create the working folder¶
With the server running, create an empty directory outside every Fotobank-managed storage root, then run:
For the full visible library:
Do not open or edit the directory until creation finishes. Fotobank copies exact Docbank versions. Each working file is a separate copy, so editing it does not change the stored version.
Relative destinations are resolved from the command's working directory. The
server validates the destination against its own storage configuration.
On Windows, use a fully qualified path such as C:\work\photos or an ordinary
relative path such as .\photos; drive-relative and drive-less rooted paths
such as C:photos and \photos are rejected.
Use --json for checkout_id, root, selected files and bytes, and
materialized (files recorded so far). Errors exit nonzero and include error.
If creation fails after reserving a checkout, the result retains its ID so you
can inspect checkout status <checkout-uuid> --json. Partial working files are
not rolled back. If the connection is lost, inspect checkout list --json for
the destination before retrying; a lost response does not mean no files were
created. Creation is not automatically retried or resumed.
The server scans active checkouts while you edit.
A tracked file must remain unchanged across separate scans spanning
checkouts.settle_interval before it becomes pending for writeback. Scanning
never commits an edit by itself.
Inspect working-copy state¶
List your checkouts and their file-state totals:
Inspect one checkout's saved selection and the files that need attention:
The status view shows pending edits, conflicts, missing files, and scan errors.
Use --json with either command for scripts and agents. The results show the
daemon's last saved observations, not a new scan. New untracked files are not
included in this status view.
For an edited file, find its path in problems. Wait for its state to be
pending and its observed_sha256 to match the bytes you intend to commit.
checkout.entries.pending is only a count: editing an already-pending file does
not increase it, and zero does not prove that a recent edit has been scanned.
Check again after the configured scan and settle intervals, and stop on missing
files, conflicts, or errors.
Commit tracked edits¶
Wait for the server's scanner to mark the edits pending and check status.
Keep the server running. Do not edit the working files during
commit. Use the checkout identifier printed by checkout create:
Each changed tracked file becomes a new immutable Docbank version. If the stored base version has changed, Fotobank reports a conflict and keeps the newer version. Current writeback does not import new untracked files, apply deletions, infer renames, or resolve conflicts.
JSON output contains checkout_id, pending, committed, and conflicts, with
an error when work fails. Some entries may commit before another fails; inspect
the counts even on a nonzero exit. If you cancel or lose the connection, inspect
checkout status <checkout-uuid> --json before retrying. Committed versions
remain committed; retrying does not repeat an already completed entry.
To check what was saved, inspect the photo again and download it to a new path:
fotobank media show <media-uuid> --json
fotobank media download <media-uuid> --output /work/verified-photo.jpg --json
Compare the returned checksum with the edit you intended to save. The download verifies the stored bytes; it does not read the working copy. See downloads for destination requirements and retry behavior.
Uncommitted working files are excluded from archive backups. Commit edits before capturing an archive that must include them. Automatic reconstruction of working trees is not yet exposed as a command.
Stop tracking a working folder¶
Retirement stops Fotobank scanning or committing a checkout. The working files stay where they are; Docbank originals and versions are unchanged.
The first command only shows the last recorded status. Review pending edits, conflicts, missing files and errors before confirming. This is not a fresh scan: external edits may be newer than the recorded observations. Commit any edits you want saved to Docbank before retiring; retirement does not save them.
The confirmed command uses the normal daemon and waits for in-flight checkout
work to finish. It retains the history in checkout list and checkout status,
including their JSON output, and releases the folder reservation. It can retire
a missing folder or an incomplete checkout, and repeating it is harmless.
There is no reactivation command. A new checkout still requires an empty folder;
Fotobank will not adopt or overwrite the files left by the retired checkout.