txn

Documentation

Overview

Package txn — typed Reversible-Action layer (spec/04-generic-cli/29).

This sits ON TOP of the existing TransactionFile byte-snapshot journal:

• RecordEditFile → snapshots bytes (TransactionFile row) AND writes an edit_file action row with a BackupRef pointer.
• RecordRenamePath → writes a rename_path action row only (no bytes).

On revert (RevertActions), rows are walked Seq DESC and dispatched per-Kind. Handlers are pure: they operate on the JSON payload + the referenced TransactionFile row, and they are idempotent — replaying a reverse on already-reverted state returns nil.

Package txn is the SQLite-backed transaction journal that gives every state-mutating gitmap command a recorded, revertable trail.

Spec: spec/04-generic-cli/28-transaction-revert.md

Lifecycle:

t, _ := txn.Begin(db, txn.Meta{Kind: TxnKindMv, Argv: os.Args, ...})
t.RecordRename(absFrom, absTo)            // bytes-free rename
t.SnapshotEdit(absPath)                    // before mutating in place
t.SnapshotDelete(absPath)                  // before unlinking
if err != nil { t.Abort(); return err }
t.Commit()

Backups land at:

<binaryDir>/.gitmap/txn/<txnId>/data/<repoSlug>/<gitSha>/files/<rel>

Index

• func Revert(db *store.DB, id int64, opts RevertOptions) error
• func RevertActions(db *store.DB, txnID int64) error
• type EditFilePayload
• type Journal
  • func Begin(db *store.DB, m Meta) (*Journal, error)
  • func (j *Journal) Abort() error
  • func (j *Journal) Commit() error
  • func (j *Journal) ID() int64
  • func (j *Journal) RecordEditFile(absPath string) error
  • func (j *Journal) RecordRename(from, to string) error
  • func (j *Journal) RecordRenamePath(from, to string) error
  • func (j *Journal) SnapshotDelete(absPath string) error
  • func (j *Journal) SnapshotEdit(absPath string) error
• type Meta
• type RenamePathPayload
• type RevertOptions

Functions

func Revert

func Revert(db *store.DB, id int64, opts RevertOptions) error

Revert applies the inverse of one committed transaction:

• delete → restore file bytes from backup
• edit → overwrite current bytes with backup
• rename → swap the path back (no bytes copied)

func RevertActions

func RevertActions(db *store.DB, txnID int64) error

RevertActions replays the typed-action chain in Seq DESC order. This is the public entry point used by the v23+ revert path; it is a peer to (not a replacement for) the legacy file-only Revert.

Types

type EditFilePayload

type EditFilePayload struct {
	AbsPath string `json:"absPath"`
	Sha256  string `json:"sha256,omitempty"`
}

EditFilePayload describes the forward side of edit_file. The reverse side is the same struct with BackupRef populated by the journal.

type Journal

type Journal struct {
	// contains filtered or unexported fields
}

Journal is a live transaction handle.

func Begin

func Begin(db *store.DB, m Meta) (*Journal, error)

Begin inserts a pending row and returns a handle the caller commits or aborts. The returned *Journal is never nil even when SQLite errors — callers can safely defer Abort() and unconditionally call snapshot helpers, which degrade to no-ops when id == 0.

func (*Journal) Abort

func (j *Journal) Abort() error

Abort flips the row to aborted and removes any partial backup dir.

func (*Journal) Commit

func (j *Journal) Commit() error

Commit flips the row to committed and prunes anything beyond the cap.

func (*Journal) ID

func (j *Journal) ID() int64

ID returns the journal row id (0 when Begin's INSERT failed).

func (*Journal) RecordEditFile

func (j *Journal) RecordEditFile(absPath string) error

RecordEditFile snapshots absPath bytes (reusing SnapshotEdit) AND writes an edit_file action row pointing at the byte-backup row.

func (*Journal) RecordRename

func (j *Journal) RecordRename(from, to string) error

RecordRename logs a directory- or file-rename so revert can swap it back. Bytes are NOT copied — the rename is the inverse of a rename.

func (*Journal) RecordRenamePath

func (j *Journal) RecordRenamePath(from, to string) error

RecordRenamePath logs from→to (no bytes). Reverse swaps the pair.

func (*Journal) SnapshotDelete

func (j *Journal) SnapshotDelete(absPath string) error

SnapshotDelete copies the file aside and records a "delete" row. Call BEFORE removing absPath from disk.

func (*Journal) SnapshotEdit

func (j *Journal) SnapshotEdit(absPath string) error

SnapshotEdit copies the current bytes of absPath into the backup tree and records an "edit" row. Call BEFORE the in-place mutation.

type Meta

type Meta struct {
	Kind           string   // TxnKind* constant
	Argv           []string // os.Args verbatim, joined for the journal row
	Cwd            string   // process working directory at command start
	ReverseSummary string   // one-line "what revert will do"
	RepoSlug       string   // empty when not repo-scoped
	GitSha         string   // resolved HEAD; "" → TxnUnknownGitShaMarker
}

Meta is the per-command context every transaction needs at Begin time.

type RenamePathPayload

type RenamePathPayload struct {
	From string `json:"from"`
	To   string `json:"to"`
}

RenamePathPayload describes both sides of rename_path; reverse swaps From and To.

type RevertOptions

type RevertOptions struct {
	Force bool // skip pre-revert sha256 verification of backup blobs
}

RevertOptions tunes Revert behavior.