TerminusDB.Branch (terminusdb_ex v0.3.3)

Copy Markdown View Source

Branch management API for TerminusDB.

Wraps the /api/branch/{path} endpoints. Branches are git-like pointers to commits within a repository. Creating a branch forks from an existing branch (default: main).

All functions require a TerminusDB.Config scoped to a database (via TerminusDB.Config.with_database/2). The organization defaults to config.organization and the repository to config.repo (default local), both overridable per call.

Quick start

config =
  TerminusDB.Config.new(endpoint: "http://localhost:6363")
  |> TerminusDB.Config.with_database("mydb")

# Create a branch (forks from main by default)
{:ok, _} = TerminusDB.Branch.create(config, "feature")

# Check it exists
true = TerminusDB.Branch.exists?(config, "feature")

# Delete it
{:ok, _} = TerminusDB.Branch.delete(config, "feature")

Summary

Types

branch_opt()

Functions

create(config, branch_name, opts \\ [])

Creates a new branch branch_name in the configured (or given) repository.

create!(config, branch_name, opts \\ [])

Creates a branch, returning the response body or raising TerminusDB.Error.

delete(config, branch_name, opts \\ [])

Deletes the branch branch_name.

delete!(config, branch_name, opts \\ [])

Deletes a branch, returning the response body or raising TerminusDB.Error.

exists?(config, branch_name, opts \\ [])

Returns true if the branch branch_name exists, false otherwise.

reset(config, commit_descriptor, opts \\ [])

Hard-resets the branch HEAD to a specific commit.

reset!(config, commit_descriptor, opts \\ [])

Hard-resets the branch HEAD, or raises.

squash(config, opts \\ [])

Squashes the current branch HEAD into a single commit.

squash!(config, opts \\ [])

Squashes the branch HEAD, or raises.

Types

branch_opt()

@type branch_opt() ::
  {:organization, String.t()}
  | {:repo, String.t()}
  | {:from, String.t()}
  | {:author, String.t()}
  | {:message, String.t()}

Functions

create(config, branch_name, opts \\ [])

@spec create(TerminusDB.Config.t(), String.t(), [branch_opt()]) ::
  {:ok, map()} | {:error, TerminusDB.Error.t()}

Creates a new branch branch_name in the configured (or given) repository.

The branch is forked from the branch named in :from (default: config.branch, which defaults to "main").

Options

  • :from — the branch to fork from (default: config.branch).
  • :organization — overrides config.organization.
  • :repo — overrides config.repo (local or a remote name).

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> {:ok, resp} = TerminusDB.Branch.create(config, "feature")
iex> resp["api:status"]
"api:success"

Fork from a specific branch:

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> {:ok, resp} = TerminusDB.Branch.create(config, "dev", from: "main")
iex> resp["api:status"]
"api:success"

create!(config, branch_name, opts \\ [])

@spec create!(TerminusDB.Config.t(), String.t(), [branch_opt()]) :: map()

Creates a branch, returning the response body or raising TerminusDB.Error.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> TerminusDB.Branch.create!(config, "feature")
%{"api:status" => "api:success"}

delete(config, branch_name, opts \\ [])

@spec delete(TerminusDB.Config.t(), String.t(), [branch_opt()]) ::
  {:ok, map() | nil} | {:error, TerminusDB.Error.t()}

Deletes the branch branch_name.

Options

  • :organization — overrides config.organization.
  • :repo — overrides config.repo.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> {:ok, resp} = TerminusDB.Branch.delete(config, "feature")
iex> resp["api:status"]
"api:success"

delete!(config, branch_name, opts \\ [])

@spec delete!(TerminusDB.Config.t(), String.t(), [branch_opt()]) :: map() | nil

Deletes a branch, returning the response body or raising TerminusDB.Error.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> TerminusDB.Branch.delete!(config, "feature")
%{"api:status" => "api:success"}

exists?(config, branch_name, opts \\ [])

@spec exists?(TerminusDB.Config.t(), String.t(), [branch_opt()]) :: boolean()

Returns true if the branch branch_name exists, false otherwise.

Checks the database's branch list via GET /api/db/:org/:db?branches=true. A 404 on the database means it does not exist (so the branch cannot either); any other non-success response raises TerminusDB.Error.

Options

  • :organization — overrides config.organization.
  • :repo — overrides config.repo.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req ->
...>     {req, Req.Response.new(status: 200, body: %{"branches" => ["main", "feature"], "path" => "admin/mydb"})}
...>   end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> TerminusDB.Branch.exists?(config, "main")
true

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req ->
...>     {req, Req.Response.new(status: 200, body: %{"branches" => ["main"], "path" => "admin/mydb"})}
...>   end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> TerminusDB.Branch.exists?(config, "missing")
false

reset(config, commit_descriptor, opts \\ [])

@spec reset(TerminusDB.Config.t(), String.t(), [branch_opt()]) ::
  {:ok, map()} | {:error, TerminusDB.Error.t()}

Hard-resets the branch HEAD to a specific commit.

Options

  • :organization — overrides config.organization.
  • :repo — overrides config.repo.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> {:ok, resp} = TerminusDB.Branch.reset(config, "admin/mydb/local/commit/abc123")
iex> resp["api:status"]
"api:success"

reset!(config, commit_descriptor, opts \\ [])

@spec reset!(TerminusDB.Config.t(), String.t(), [branch_opt()]) :: map()

Hard-resets the branch HEAD, or raises.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> TerminusDB.Branch.reset!(config, "admin/mydb/local/commit/abc")
%{"api:status" => "api:success"}

squash(config, opts \\ [])

@spec squash(TerminusDB.Config.t(), [branch_opt()]) ::
  {:ok, map()} | {:error, TerminusDB.Error.t()}

Squashes the current branch HEAD into a single commit.

Options

  • :author — commit author.
  • :message — commit message.
  • :organization — overrides config.organization.
  • :repo — overrides config.repo.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success", "api:commit" => "abc123"})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> {:ok, resp} = TerminusDB.Branch.squash(config, author: "admin", message: "squash")
iex> resp["api:commit"]
"abc123"

squash!(config, opts \\ [])

@spec squash!(TerminusDB.Config.t(), [branch_opt()]) :: map()

Squashes the branch HEAD, or raises.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success", "api:commit" => "abc"})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> TerminusDB.Branch.squash!(config, author: "admin", message: "squash")
%{"api:commit" => "abc"}