Git operations and EDN file I/O for the git adapter.
Hybrid engine: most read and write operations use JGit in-process when a Repository is available, falling back to CLI shell-outs. The git CLI is also used for worktree operations JGit 7.x does not support. Files are EDN maps, one entity per file.
Git operations and EDN file I/O for the git adapter. Hybrid engine: most read and write operations use JGit in-process when a Repository is available, falling back to CLI shell-outs. The git CLI is also used for worktree operations JGit 7.x does not support. Files are EDN maps, one entity per file.
(add-worktree! repo-dir worktree-path branch)Add a new worktree at the given path, creating a new branch. The branch is named after the last path component (e.g. conv-<uuid>). Uses JGit in-process when available, falls back to CLI. Invalidates the branch cache on success.
Arguments:
Returns {:success bool, :path string, :branch string}.
Add a new worktree at the given path, creating a new branch.
The branch is named after the last path component (e.g. conv-<uuid>).
Uses JGit in-process when available, falls back to CLI.
Invalidates the branch cache on success.
Arguments:
- repo-dir: path to the bare repo
- worktree-path: absolute or relative path for the new worktree
- branch: branch name for this worktree
Returns {:success bool, :path string, :branch string}.(bare-repo-status dir)Return status for a bare repo: {:initialized? bool, :head string, :worktree-count int}. Uses JGit when available for HEAD resolution and worktree listing.
Return status for a bare repo: {:initialized? bool, :head string, :worktree-count int}.
Uses JGit when available for HEAD resolution and worktree listing.(bare-repo? dir)Returns true if the directory is a bare git repository. Uses JGit when available, falls back to CLI.
Returns true if the directory is a bare git repository. Uses JGit when available, falls back to CLI.
(child-entity-path repo-dir
parent-entity-dir
parent-id
child-dir
child-id
{:keys [extension]})Build the file path for a scoped child entity inside a parent directory. Path: repo-dir/parent-entity-dir/parent-id/child-dir/child-id.ext child-dir is typically derived from (name ref-attribute-key).
Build the file path for a scoped child entity inside a parent directory. Path: repo-dir/parent-entity-dir/parent-id/child-dir/child-id.ext child-dir is typically derived from (name ref-attribute-key).
(commit-entity! repo-dir file-path message)Stage and commit only the entity file — nothing else in the index.
Equivalent of git add path && git commit --only path -m message.
Uses JGit in-process when Repository is available, falls back to CLI.
Returns {:success bool, :commit string}.
Stage and commit only the entity file — nothing else in the index.
Equivalent of `git add path && git commit --only path -m message`.
Uses JGit in-process when Repository is available, falls back to CLI.
Returns {:success bool, :commit string}.(commit-files! repo-dir file-specs message)Stage and commit multiple files atomically — one commit for all paths. Each file-spec is a map with :path (absolute) and :action (:add or :delete). Files marked :delete are removed from disk before staging.
This is the multi-file equivalent of commit-entity! — ensures state + event deletion happen in a single atomic commit (no partial state visible in history). Uses JGit in-process when Repository is available, falls back to CLI.
Arguments:
Returns {:success bool, :commit string}.
Stage and commit multiple files atomically — one commit for all paths.
Each file-spec is a map with :path (absolute) and :action (:add or :delete).
Files marked :delete are removed from disk before staging.
This is the multi-file equivalent of commit-entity! — ensures state + event
deletion happen in a single atomic commit (no partial state visible in history).
Uses JGit in-process when Repository is available, falls back to CLI.
Arguments:
- repo-dir: path to the repo (normal or worktree)
- file-specs: seq of {:path string, :action :add|:delete}
- message: commit message
Returns {:success bool, :commit string}.(delete-and-commit! repo-dir file-path message)Remove a file and commit only the deletion — nothing else in the index.
Equivalent of rm path && git add path && git commit --only path -m message.
Uses JGit in-process when Repository is available, falls back to CLI.
Returns {:success bool}.
Remove a file and commit only the deletion — nothing else in the index.
Equivalent of `rm path && git add path && git commit --only path -m message`.
Uses JGit in-process when Repository is available, falls back to CLI.
Returns {:success bool}.(delete-branch! repo-dir branch)Delete a branch from the repository. Used for cleanup after a session ends and its history is no longer needed. Uses JGit in-process when available, falls back to CLI. Invalidates the branch cache on success.
Refuses to delete branches that currently have an active worktree (use remove-worktree! first). Uses -D (force delete) since the branch may not be fully merged into main.
Arguments:
Returns {:success bool}.
Delete a branch from the repository. Used for cleanup after a session
ends and its history is no longer needed. Uses JGit in-process when
available, falls back to CLI. Invalidates the branch cache on success.
Refuses to delete branches that currently have an active worktree
(use remove-worktree! first). Uses -D (force delete) since the branch
may not be fully merged into main.
Arguments:
- repo-dir: path to the bare repo
- branch: branch name to delete
Returns {:success bool}.(delete-entity-dir! path)Recursively delete an entity directory and all its contents. Returns true if deleted.
Recursively delete an entity directory and all its contents. Returns true if deleted.
(delete-entity-file! path)Delete an entity file. Returns true if deleted.
Delete an entity file. Returns true if deleted.
(embed-available?)Returns true if git-embed is installed and accessible on the PATH.
git-embed provides semantic similarity search over git repository content.
See: https://github.com/michaelwhitford/git-embed
Returns true if `git-embed` is installed and accessible on the PATH. git-embed provides semantic similarity search over git repository content. See: https://github.com/michaelwhitford/git-embed
(embed-gc! dir & [{:keys [model]}])Remove embeddings for deleted files from the index. Uses in-process JGit when :model is provided (pure index operation — no ONNX inference required, but model presence signals in-process path is live). Falls back to git-embed CLI.
Arguments:
Returns {:success bool}.
Remove embeddings for deleted files from the index.
Uses in-process JGit when :model is provided (pure index operation — no
ONNX inference required, but model presence signals in-process path is live).
Falls back to git-embed CLI.
Arguments:
- dir: path to the git repo
- opts: optional map with:
:model - EmbedModel from coordinator WM (nil → CLI fallback)
Returns {:success bool}.(embed-install! dir)Install git-embed hooks (post-commit, post-merge, post-checkout) on a repo. After installation, embeddings update automatically on every commit. Requires git-embed to be installed.
Arguments:
Returns {:success bool, :message string}.
Install git-embed hooks (post-commit, post-merge, post-checkout) on a repo.
After installation, embeddings update automatically on every commit.
Requires git-embed to be installed.
Arguments:
- dir: path to the git repo (normal or bare)
Returns {:success bool, :message string}.(embed-search dir query & [{:keys [model top dims path] :as opts}])Semantic search across indexed content in a git repository. Uses in-process ONNX embeddings when :model is provided (from embeddings providing statechart WM), falls back to git-embed CLI.
Arguments:
Returns seq of {:score float, :path string} sorted by relevance, or nil if neither in-process model nor git-embed CLI is available.
Semantic search across indexed content in a git repository.
Uses in-process ONNX embeddings when :model is provided (from embeddings
providing statechart WM), falls back to git-embed CLI.
Arguments:
- dir: path to the git repo (or worktree)
- query: search query string
- opts: optional map with:
:model - EmbedModel from coordinator WM (nil → CLI fallback)
:top - number of results (default: 10)
:dims - truncation dimensions (64, 128, 256, 384, 512, 768)
:path - restrict search to path prefix
Returns seq of {:score float, :path string} sorted by relevance,
or nil if neither in-process model nor git-embed CLI is available.(embed-similar dir file-path & [{:keys [model top dims path] :as opts}])Find files similar to a given file in a git repository. Uses in-process JGit when :model is provided (index-only operation — model is not used for inference here, only as a signal that in-process path is live). Falls back to git-embed CLI.
Arguments:
Returns seq of {:score float, :path string} sorted by similarity, or nil if neither in-process path nor git-embed CLI is available.
Find files similar to a given file in a git repository.
Uses in-process JGit when :model is provided (index-only operation — model
is not used for inference here, only as a signal that in-process path is live).
Falls back to git-embed CLI.
Arguments:
- dir: path to the git repo (or worktree)
- file-path: relative path to the file within the repo
- opts: optional map with:
:model - EmbedModel from coordinator WM (nil → CLI fallback)
:top - number of results (default: 10)
:dims - truncation dimensions (64, 128, 256, 384, 512, 768)
:path - restrict search to path prefix
Returns seq of {:score float, :path string} sorted by similarity,
or nil if neither in-process path nor git-embed CLI is available.(embed-status dir)Get the embedding index status for a git repository. Requires git-embed to be installed.
Arguments:
Returns map of {:model string, :indexed int, :total int, :dims int, :ref string, :hooks string}, or nil if git-embed is not available.
Get the embedding index status for a git repository.
Requires git-embed to be installed.
Arguments:
- dir: path to the git repo
Returns map of {:model string, :indexed int, :total int, :dims int,
:ref string, :hooks string},
or nil if git-embed is not available.(embed-uninstall! dir)Remove git-embed hooks from a repo.
Arguments:
Returns {:success bool}.
Remove git-embed hooks from a repo.
Arguments:
- dir: path to the git repo
Returns {:success bool}.(embed-update! dir & [{:keys [model verbose?]}])Index all unindexed text files in HEAD. Uses in-process ONNX embeddings when :model is provided (from embeddings providing statechart WM), falls back to git-embed CLI.
Arguments:
Returns {:success bool, :message string}.
Index all unindexed text files in HEAD.
Uses in-process ONNX embeddings when :model is provided (from embeddings
providing statechart WM), falls back to git-embed CLI.
Arguments:
- dir: path to the git repo
- opts: optional map with:
:model - EmbedModel from coordinator WM (nil → CLI fallback)
:verbose? - boolean (CLI path only)
Returns {:success bool, :message string}.(entity-history repo-dir file-path & [{:keys [limit] :or {limit 20}}])Get git log for an entity file. Returns seq of {:hash :time :message}. Uses JGit in-process when Repository is available, falls back to CLI.
Get git log for an entity file. Returns seq of {:hash :time :message}.
Uses JGit in-process when Repository is available, falls back to CLI.(entity-path repo-dir entity-dir id)(entity-path repo-dir entity-dir id {:keys [extension directory?]})Build the file path for an entity. For flat entities: repo-dir/entity-dir/id.ext (a file path). For directory entities (opts {:directory? true}): repo-dir/entity-dir/id (a directory path). Extension defaults to .edn. Pass opts {:extension ".md"} to override.
Build the file path for an entity.
For flat entities: repo-dir/entity-dir/id.ext (a file path).
For directory entities (opts {:directory? true}): repo-dir/entity-dir/id (a directory path).
Extension defaults to .edn. Pass opts {:extension ".md"} to override.(fork-worktree! repo-dir worktree-path branch start-point)Add a worktree branching from a specific commit SHA. Used for conversation forking — new branch starts at the given point. Uses JGit in-process when available, falls back to CLI. Invalidates the branch cache on success.
Arguments:
Returns {:success bool, :path string, :branch string}.
Add a worktree branching from a specific commit SHA.
Used for conversation forking — new branch starts at the given point.
Uses JGit in-process when available, falls back to CLI.
Invalidates the branch cache on success.
Arguments:
- repo-dir: path to the bare repo
- worktree-path: path for the new worktree
- branch: new branch name
- start-point: commit SHA or branch to fork from
Returns {:success bool, :path string, :branch string}.(gc! repo-dir & [{:keys [aggressive?]}])Run git garbage collection on a repo. Use after removing worktrees to reclaim disk space. Uses JGit in-process when available, falls back to CLI.
Arguments:
Returns {:success bool}.
Run git garbage collection on a repo. Use after removing worktrees
to reclaim disk space. Uses JGit in-process when available, falls
back to CLI.
Arguments:
- repo-dir: path to the repo
- opts: optional map with :aggressive? boolean
Returns {:success bool}.(git! dir & args)Execute a git command in the given directory. Returns {:exit :out :err}. Reads stdout/stderr concurrently with waitFor to avoid pipe buffer deadlock (OS pipe buffer is ~64KB; if the child fills it before we read, the child blocks on write and waitFor never returns).
Execute a git command in the given directory. Returns {:exit :out :err}.
Reads stdout/stderr concurrently with waitFor to avoid pipe buffer deadlock
(OS pipe buffer is ~64KB; if the child fills it before we read, the child
blocks on write and waitFor never returns).(git-available?)Returns true if git is installed and accessible on the PATH.
Checks by running git --version.
Returns true if `git` is installed and accessible on the PATH. Checks by running `git --version`.
(git-ok? dir & args)Execute a git command, return true if exit 0.
Execute a git command, return true if exit 0.
(index-file-path repo-dir entity-dir id identity-ns opts)Build the full path to a directory entity's index file. Composes entity-path (directory) + index-filename.
Build the full path to a directory entity's index file. Composes entity-path (directory) + index-filename.
(index-filename identity-ns {:keys [extension]})Derive the index filename for a directory entity from its identity attribute's namespace + file extension. E.g. :experiment/id → "experiment.edn". The identity-ns argument is the namespace string of the identity qualified key.
Derive the index filename for a directory entity from its identity attribute's namespace + file extension. E.g. :experiment/id → "experiment.edn". The identity-ns argument is the namespace string of the identity qualified key.
(init-bare! dir)Initialize a bare git repository at the given path. Bare repos have no working directory — use worktrees for working dirs. Creates an initial empty commit on the main branch so worktrees can branch from HEAD. Uses JGit in-process when available, falls back to CLI. Returns the canonical directory path.
Initialize a bare git repository at the given path. Bare repos have no working directory — use worktrees for working dirs. Creates an initial empty commit on the main branch so worktrees can branch from HEAD. Uses JGit in-process when available, falls back to CLI. Returns the canonical directory path.
(init-repo! dir)Ensure a directory is a git repository. Initializes if needed. Returns the canonical directory path.
Ensure a directory is a git repository. Initializes if needed. Returns the canonical directory path.
(invalidate-branch-cache! repo-dir)Invalidate the branch name cache for a repo directory. Called automatically by branch-mutating operations. Can be called manually if branches are modified outside this API.
Invalidate the branch name cache for a repo directory. Called automatically by branch-mutating operations. Can be called manually if branches are modified outside this API.
(list-branch-names repo-dir)List all branch names in a repository. Returns a set of branch name strings (without refs/heads/ prefix).
Results are cached per repo-dir. The cache is invalidated by branch-mutating operations (add-worktree!, restore-worktree!, delete-branch!). When the cache is cold, uses JGit in-process when a Repository is available, falls back to CLI.
Arguments:
Returns set of branch name strings.
List all branch names in a repository. Returns a set of branch name strings (without refs/heads/ prefix). Results are cached per repo-dir. The cache is invalidated by branch-mutating operations (add-worktree!, restore-worktree!, delete-branch!). When the cache is cold, uses JGit in-process when a Repository is available, falls back to CLI. Arguments: - repo-dir: path to the repo (bare or normal) Returns set of branch name strings.
(list-children repo-dir parent-entity-dir parent-id child-dir)(list-children repo-dir
parent-entity-dir
parent-id
child-dir
{:keys [extension read-fn]})List child entity files in a subdirectory of a parent directory entity. Path scanned: repo-dir/parent-entity-dir/parent-id/child-dir/ Returns seq of {:id string, :path string, :entity map}. Extension defaults to .edn.
List child entity files in a subdirectory of a parent directory entity.
Path scanned: repo-dir/parent-entity-dir/parent-id/child-dir/
Returns seq of {:id string, :path string, :entity map}.
Extension defaults to .edn.(list-directory-entities repo-dir entity-dir identity-ns)(list-directory-entities repo-dir
entity-dir
identity-ns
{:keys [extension read-fn] :as opts})List directory entities — each subdirectory in entity-dir is an entity instance. Reads the index file inside each subdirectory. Returns seq of {:id string, :path string, :entity map}. identity-ns: namespace of the identity key (e.g. "experiment").
List directory entities — each subdirectory in entity-dir is an entity instance.
Reads the index file inside each subdirectory.
Returns seq of {:id string, :path string, :entity map}.
identity-ns: namespace of the identity key (e.g. "experiment").(list-entities repo-dir entity-dir)(list-entities repo-dir entity-dir {:keys [extension read-fn]})List entity files in an entity directory. Returns seq of {:id string, :path string, :entity map}. Extension defaults to .edn. Pass opts {:extension ".md" :read-fn f} to override.
List entity files in an entity directory.
Returns seq of {:id string, :path string, :entity map}.
Extension defaults to .edn. Pass opts {:extension ".md" :read-fn f} to override.(list-entities-recursive repo-dir entity-dir)(list-entities-recursive repo-dir entity-dir {:keys [extension read-fn]})List entity files recursively in an entity directory and its subdirectories. Returns seq of {:id string, :path string, :entity map}.
The :id is the relative path from entity-dir without extension, e.g. for mementum/knowledge/architecture/statecharts.md → "architecture/statecharts".
Options: :extension - file extension filter (default: ".edn") :read-fn - custom deserialization function
List entity files recursively in an entity directory and its subdirectories.
Returns seq of {:id string, :path string, :entity map}.
The :id is the relative path from entity-dir without extension,
e.g. for mementum/knowledge/architecture/statecharts.md → "architecture/statecharts".
Options:
:extension - file extension filter (default: ".edn")
:read-fn - custom deserialization function(list-entities-sorted repo-dir entity-dir)(list-entities-sorted repo-dir
entity-dir
{:keys [extension read-fn sort-fn sort-dir]
:or {sort-dir :asc}})List entity files in a directory, sorted by a caller-provided function. Like list-entities but with guaranteed ordering — required for ordered event consumption (e.g., processing events by timestamp).
The sort-fn receives the entity map and should return a Comparable value. Default sort: alphabetical by :id.
Options: :extension - file extension filter (default: ".edn") :read-fn - custom deserialization function :sort-fn - (fn [entity-map]) → Comparable (default: :id) :sort-dir - :asc or :desc (default: :asc)
Returns vector of {:id string, :path string, :entity map}, sorted.
List entity files in a directory, sorted by a caller-provided function.
Like list-entities but with guaranteed ordering — required for ordered
event consumption (e.g., processing events by timestamp).
The sort-fn receives the entity map and should return a Comparable value.
Default sort: alphabetical by :id.
Options:
:extension - file extension filter (default: ".edn")
:read-fn - custom deserialization function
:sort-fn - (fn [entity-map]) → Comparable (default: :id)
:sort-dir - :asc or :desc (default: :asc)
Returns vector of {:id string, :path string, :entity map}, sorted.(list-worktrees repo-dir)List all worktrees for a repo. Returns seq of {:path :head :branch :bare}. Uses JGit when available, falls back to CLI porcelain parsing. The first entry is the bare repo itself (branch = bare).
List all worktrees for a repo. Returns seq of {:path :head :branch :bare}.
Uses JGit when available, falls back to CLI porcelain parsing.
The first entry is the bare repo itself (branch = bare).(parse-frontmatter content)Parse YAML frontmatter from a string. Returns {:frontmatter map, :body string}. If no frontmatter delimiter is present, returns {:frontmatter nil, :body content}. Frontmatter keys are keywords. YAML lists become vectors.
Body content here.
Parse YAML frontmatter from a string. Returns {:frontmatter map, :body string}.
If no frontmatter delimiter is present, returns {:frontmatter nil, :body content}.
Frontmatter keys are keywords. YAML lists become vectors.
Standard format:
---
title: My Page
tags: [a, b]
---
Body content here.(prune-worktrees! repo-dir)Prune stale worktree bookkeeping data. Cleans up references to worktrees whose directories have been removed externally. Uses JGit in-process when available, falls back to CLI.
Arguments:
Returns {:success bool}.
Prune stale worktree bookkeeping data. Cleans up references to worktrees
whose directories have been removed externally.
Uses JGit in-process when available, falls back to CLI.
Arguments:
- repo-dir: path to the bare repo
Returns {:success bool}.(read-entity path)(read-entity path {:keys [read-fn]})Read an entity file. Returns the parsed data or nil. Default: parses EDN. Pass opts {:read-fn f} for custom deserialization.
Read an entity file. Returns the parsed data or nil.
Default: parses EDN. Pass opts {:read-fn f} for custom deserialization.(remove-worktree! repo-dir worktree-path & [{:keys [force?] :or {force? true}}])Remove a worktree. Keeps the branch for historical access via git log. Uses JGit in-process when available, falls back to CLI. Uses --force by default to handle untracked/modified files.
Arguments:
Returns {:success bool}.
Remove a worktree. Keeps the branch for historical access via git log.
Uses JGit in-process when available, falls back to CLI.
Uses --force by default to handle untracked/modified files.
Arguments:
- repo-dir: path to the bare repo
- worktree-path: path of the worktree to remove
- opts: optional map with :force? boolean (default true)
Returns {:success bool}.(render-frontmatter frontmatter body)Render a map as YAML frontmatter prepended to a body string. Returns the combined string. If frontmatter is nil or empty, returns body only.
Example: (render-frontmatter {:title "My Page" :tags ["a" "b"]} "Body here") => "---\ntitle: My Page\ntags:\n- a\n- b\n---\n\nBody here"
Render a map as YAML frontmatter prepended to a body string.
Returns the combined string. If frontmatter is nil or empty, returns body only.
Example:
(render-frontmatter {:title "My Page" :tags ["a" "b"]} "Body here")
=> "---\ntitle: My Page\ntags:\n- a\n- b\n---\n\nBody here"(repo-status dir)Return repo status: {:initialized? bool, :file-count int, :head string}. Counts entity files with extensions matching known types (.edn, .md, etc.). Uses JGit for HEAD resolution when available.
Return repo status: {:initialized? bool, :file-count int, :head string}.
Counts entity files with extensions matching known types (.edn, .md, etc.).
Uses JGit for HEAD resolution when available.(restore-worktree! repo-dir worktree-path branch)Re-attach a worktree to an existing branch on restart. If the branch already exists (from a previous session), creates a new worktree at worktree-path checked out on that branch.
Unlike add-worktree! which creates a new branch, this attaches to an existing branch — used for crash recovery / restart scenarios where the worktree directory was removed but the branch persists.
Arguments:
Returns {:success bool, :path string, :branch string}.
Re-attach a worktree to an existing branch on restart. If the branch
already exists (from a previous session), creates a new worktree at
worktree-path checked out on that branch.
Unlike add-worktree! which creates a *new* branch, this attaches to
an *existing* branch — used for crash recovery / restart scenarios
where the worktree directory was removed but the branch persists.
Arguments:
- repo-dir: path to the bare repo
- worktree-path: path for the worktree directory
- branch: existing branch name to attach
Returns {:success bool, :path string, :branch string}.(search-content repo-dir query & [{:keys [entity-dir]}])Search entity files via git grep. Returns seq of {:path :line :match}. Uses JGit in-process when Repository is available, falls back to CLI.
Search entity files via git grep. Returns seq of {:path :line :match}.
Uses JGit in-process when Repository is available, falls back to CLI.(source-file-path repo-dir entity-dir id source-file)Build the full path to a named file within a directory entity. For ::gto/source-file attributes. The source-file argument is the explicit filename (e.g. "summary.edn").
Build the full path to a named file within a directory entity. For ::gto/source-file attributes. The source-file argument is the explicit filename (e.g. "summary.edn").
(worktree-commit! worktree-path file-path message)Stage and commit a file within a worktree. Like commit-entity! but operates in a worktree directory rather than the main repo. Uses JGit in-process when Repository is available, falls back to CLI.
Arguments:
Returns {:success bool, :commit string}.
Stage and commit a file within a worktree. Like commit-entity! but
operates in a worktree directory rather than the main repo.
Uses JGit in-process when Repository is available, falls back to CLI.
Arguments:
- worktree-path: path to the worktree directory
- file-path: absolute path to the file to commit
- message: commit message
Returns {:success bool, :commit string}.(write-entity! path entity-data)(write-entity! path entity-data {:keys [write-fn]})Write entity data to a file. Creates parent dirs. Default: serializes via pr-str (EDN). Pass opts {:write-fn f} for custom serialization.
Write entity data to a file. Creates parent dirs.
Default: serializes via pr-str (EDN). Pass opts {:write-fn f} for custom serialization.cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |