@callback commit(config(), message :: String.t() | nil, opts :: keyword()) ::
  :ok | {:error, term()}

Commit staged changes with an optional message.

Creates a new revision containing all current staged changes. The exact behavior depends on the adapter implementation.

Options

• :author - Override author information for this commit
• :timestamp - Override timestamp for this commit

Examples

# Simple commit
:ok = MyAdapter.commit(config, "Add new feature")

# Commit with options
:ok = MyAdapter.commit(config, "Fix bug", author: [name: "Dev", email: "dev@example.com"])

@callback diff(
  config(),
  from_revision :: revision(),
  to_revision :: revision(),
  opts :: keyword()
) ::
  {:ok, String.t()} | {:error, term()}

Show differences between two revisions.

Examples

{:ok, diff} = MyAdapter.diff(config, "abc123", "def456")

@callback merge(
  config(),
  from_revision :: revision(),
  message :: String.t() | nil,
  opts :: keyword()
) :: :ok | {:error, term()}

Merge changes from another revision.

Examples

:ok = MyAdapter.merge(config, "feature-branch", "Merge feature branch")

@callback read_revision(config(), path :: Path.t(), revision(), opts :: keyword()) ::
  {:ok, binary()} | {:error, term()}

Read the content of a file as it existed at a specific revision.

Examples

{:ok, content} = MyAdapter.read_revision(config, "file.txt", "abc123")

@callback revisions(config(), path :: Path.t(), opts :: keyword()) ::
  {:ok, [revision_info()]} | {:error, term()}

List revisions for a given path.

Returns a list of revision information ordered by most recent first.

Options

• :limit - Maximum number of revisions to return
• :since - Only revisions after this datetime
• :until - Only revisions before this datetime
• :author - Only revisions by this author

Examples

# List all revisions for a file
{:ok, revisions} = MyAdapter.revisions(config, "file.txt")

# List last 10 revisions
{:ok, revisions} = MyAdapter.revisions(config, ".", limit: 10)

@callback rollback(config(), revision(), opts :: keyword()) :: :ok | {:error, term()}

Rollback to a previous revision.

The behavior depends on the adapter and options provided.

Options

• :path - Only rollback changes to a specific path (if supported)
• :create_commit - Whether to create a new commit for the rollback

Examples

# Rollback entire filesystem
:ok = MyAdapter.rollback(config, "abc123")

# Rollback single file
:ok = MyAdapter.rollback(config, "abc123", path: "file.txt")