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.
Interfaces
Section titled “Interfaces”| 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. |
Functions
Section titled “Functions”| 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>. |
Variables
Section titled “Variables”| 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. |