Skip to content

bulk-operation

The platform-neutral half of bulk-operation git commits: the lease-lock record, the OP<n> ids and the commit messages that carry them.

A bulk operation wrapped by BulkOperationCommitComponent lands in the vault’s git repo as one commit whose subject is OP<n>: <summary>, preceded (when the tree was dirty) by a chore: before OP<n> commit holding whatever was pending, so git revert of the OP<n> commit undoes exactly that operation. Everything in this module is pure, so it is shared by the desktop git layer and by the scheduled autocommit that reads the same lock.

The lock record and the commit message trailers are a wire format between plugins built on different copies of this library and the vault autocommit script: fields may be added, never renamed or reinterpreted.

Interface Description
BuildOperationCommitMessageParams Parameters for buildOperationCommitMessage.
BulkOperationCommit A bulk-operation commit found in the repo history.
BulkOperationLock The lease-lock record stored in .git/obsidian-bulk-operation.json while a bulk operation runs.
BulkOperationLockStalenessContext The facts isBulkOperationLockStale weighs besides the heartbeat.
OperationCommitMessage The commit message of one bulk-operation commit.
ParseBulkOperationCommitParams Parameters for parseBulkOperationCommit.
Function Description
buildBeforeOperationCommitSubject Builds the subject of the commit that saves whatever was pending before an operation.
buildOperationCommitMessage Builds the message of the commit recording a bulk operation, or an interrupted one.
formatOperationId Formats an operation id from its number.
getNextOperationId Finds the next operation id from the subjects of the bulk-operation commits already in the history.
isBulkOperationLock Checks whether a value has the shape of a BulkOperationLock.
isBulkOperationLockStale Decides whether a lease lock is stale, so whoever finds it may commit the leftovers and remove it. The heartbeat is the rule; the reboot and crashed-process checks are only fast paths that shorten the wait, and neither can make a lock with a fresh heartbeat on another machine stale.
parseBulkOperationCommit Parses a bulk-operation commit subject into the commit it describes, skipping the chore: before commits, which are not operations.
parseOperationNumber Parses the operation number out of a bulk-operation commit subject. Recognizes OP<n>: <summary>, OP<n> interrupted and chore: before OP<n>.
Variable Description
BULK_OPERATION_LOCK_FILE_NAME The name of the lease-lock file, created inside the repo’s git directory so it is never committed or synced.
BULK_OPERATION_LOCK_STALE_AFTER_IN_MILLISECONDS How long a lock may go without a heartbeat before it counts as stale. It errs long on purpose: holding a dead lock too long only makes an autocommit skip a tick, while declaring a live one stale splits its operation across two commits.
OPERATION_TRAILER_KEY The trailer key naming the operation id in a bulk-operation commit body.
PLUGIN_TRAILER_KEY The trailer key naming the plugin in a bulk-operation commit body.