phora 0.2.0

A git-based artifact package manager and multiplexer for content-addressed file distribution
Documentation
# version = 1              # optional; 1 is the only schema version and the default

# protocol selects https vs ssh for host-aliased sources; default https.
# Uncomment to flip the global default (still overridable per source):
# protocol = "ssh"

# A bare `phora add <url>` (no --to) ensures [targets.default] (path ".", flat)
# and binds the source into it. Set auto_target = false to make bare add
# declare-only (it then deploys nowhere until bound or routed with --to).
[defaults]
auto_target = true

# Pin where phora keeps its git-mirror cache and per-project state, overriding the
# XDG env vars and platform defaults. Both keys are optional and independent. A
# relative value resolves under the project root; an absolute value is used as-is.
# The configured path IS the root (no `phora` leaf is appended).
# [paths]
# cache = ".phora/cache"   # git mirrors live under <root>/git/
# state = ".phora/state"   # registry/locks/journal live under <root>/projects/

# github, gitlab, codeberg, sr.ht, bitbucket ship built in (both https + ssh),
# so a `[hosts]` block is only needed to add a forge or override auth/remote.
[hosts.github]
auth = { type = "token", env = "GITHUB_TOKEN" }

# A custom forge: `remote` is a string (https only) or a { https, ssh } table.
# Templates fill {path} verbatim; {owner} is the first segment, {repo} the rest.
[hosts.company]
remote = { https = "https://git.company.com/{path}.git", ssh = "git@git.company.com:{path}.git" }
auth = { type = "ssh", key = "~/.ssh/id_ed25519" }

# A source is a git repo, and it OWNS its selection: `root` re-anchors the slice,
# `include`/`exclude` compose `include − exclude` (exclude wins; no `!` negation).
# Pin with exactly one of branch / tag / rev (defaults to branch `main`).
# Pick exactly one source kind: forge (host + repo), local (path), literal (git),
# or url. A bare `repo = "owner/repo"` defaults to github; a bare `path` is LOCAL.

# Forge source: resolves via the host's `remote` template at sync time. `root`
# re-anchors the offer at `modules`, so artifacts are named relative to it.
[sources.dotfiles]
host = "github"          # omit to default to github when `repo` is set
repo = "me/dotfiles"     # deprecated alias: `path` (forge owner/repo) under a host
branch = "main"
root = "modules"

[sources.internal]
host = "company"
repo = "team/sub/proj"   # nested paths are fine ({owner}/{repo} ≡ {path})
protocol = "ssh"         # per-source opt-in to ssh
root = "configs"
include = ["editor", "lint"]
exclude = ["**/test/**", "**/*.bak"]

# Local source: `path` is a filesystem path used verbatim as the remote, exactly
# like a `git = "/abs/local/checkout"` alias.
[sources.scratch]
path = "~/dev/scratch-configs"
branch = "main"
root = "modules"

# Forge source pinned to a tag: the source default ref is `v0.55.0`. A binding may
# override the ref per target (see [targets.tools]), so one source can serve several
# versions at once.
[sources.fzf]
repo = "junegunn/fzf"
tag = "v0.55.0"
include = ["bin"]

# Literal remote: any https, ssh://, or scp-style URL, unchanged from before.
[sources.loqui]
git = "https://github.com/srnnkls/loqui.git"
rev = "9f1c2ab"
root = "languages"
allow_symlinks = false
preserve_executable = true
# For a local dev loop, override this source onto a local checkout and live-link
# it via `deploy = "link"` — local-overlay-only. See phora.local.example.toml.

# Url source: one of the four kinds (forge XOR local XOR git XOR url). A url downloads and
# extracts (tar, tar.gz/tgz, zip, or a raw single file named from the URL basename);
# a single top-level dir is auto-stripped, so version-stamped release tarballs need
# no per-version `root`. `branch`/`tag`/`rev`/`root` are rejected on a url source.
[sources.fzf-bin]
url = "https://github.com/junegunn/fzf/releases/download/0.55.0/fzf-0.55.0-linux_amd64.tar.gz"
# Optional integrity check, verified before extraction; a mismatch errors.
digest = "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
# digest = "blake3:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
include = ["fzf"]
# Content is imported as a deterministic, content-addressed synthetic git commit:
# identical bytes ⇒ identical commit ⇒ no lock churn.

# A target is a directory artifacts are projected into. `sources` is an explicit
# allow-list: list names to deploy them, or set `[]` (or omit the key) to deploy
# nothing. Manage the list with `phora bind`/`phora unbind`. A `sources` entry is a
# bare source name, or a table that refines how THIS target consumes the source:
# `source` = provenance, `take` = this target's own subset/rename of the offer.
[targets.neovim]
path = "~/.config/nvim"
[targets.neovim.sources]
# Alias the `dotfiles` source under a distinct `nvim` identity, then subset its
# offer to just the editor's tree with `take` (the new way a target slices a source).
nvim = { source = "dotfiles", take = ["nvim/**"] }

# One source feeding one target as two independent slices: distinct identities
# (the table keys) each `take` a different subtree, and `by-source` labels each slice.
[targets.editors]
path = "~/.config"
layout = "by-source"
[targets.editors.sources]
nvim  = { source = "dotfiles", take = ["nvim/**"] }
helix = { source = "dotfiles", take = ["helix/**"] }

# `take` can rename as it subsets: `{ src = dest }` projects one offered path to a
# new destination name, alongside literal/glob leaves it keeps as-is.
[targets.vscode]
path = "~/.config/Code/User"
layout = "flat"
[targets.vscode.sources]
dotfiles = { take = ["vscode/**", { "vscode/settings.json" = "settings.json" }] }
internal = { }

[targets.policies]
path = "~/.cupcake/policies/claude"
sources = ["loqui"]
layout = { type = "prefixed", separator = "/" }

[targets.bin]
path = "~/.local/bin"
sources = ["fzf-bin"]
layout = "flat"

# One source pinned to two versions in one project: distinct identities (the table
# keys) each pin their own ref, so a binding's branch/tag/rev overrides the source
# default for that target alone. Each distinct ref gets its own lock entry (at its own
# commit); a bare binding would inherit the source ref and share the source's single entry.
[targets.tools]
path = "~/.local/tools"
layout = "by-source"
[targets.tools.sources]
stable = { source = "fzf", tag = "v0.55.0" }
canary = { source = "fzf", tag = "v0.56.0" }