Gitility.Path (Gitility v0.4.0)

Copy Markdown View Source

Helpers for Git path bytes.

Git paths are raw binaries — arbitrary bytes with no encoding guarantee. Gitility never normalizes or re-encodes them; the raw binary is always authoritative. These helpers exist for the boundary where paths must become text:

  • display/1 — a lossy, human-readable UTF-8 string for UIs and logs.
  • encode/1 / decode/1 — a reversible, JSON-safe representation for protocols and cursors.

The reversible encoding is percent-based: %, control bytes, and bytes that are not part of a valid UTF-8 sequence are emitted as %XX; valid printable UTF-8 passes through untouched. Any valid UTF-8 path without a % therefore encodes to itself.

iex> Gitility.Path.encode("lib/widget.ex")
"lib/widget.ex"

iex> encoded = Gitility.Path.encode(<<"caf", 0xE9, ".txt">>)
iex> Gitility.Path.decode(encoded)
<<"caf", 0xE9, ".txt">>

Summary

Functions

decode(encoded)

Restores the exact original path bytes from encode/1 output.

display(path)

A lossy, printable representation of a Git path for humans.

encode(path)

A reversible, JSON-safe (valid UTF-8) representation of a Git path.

Functions

decode(encoded)

@spec decode(String.t()) :: binary()

Restores the exact original path bytes from encode/1 output.

display(path)

@spec display(binary()) :: String.t()

A lossy, printable representation of a Git path for humans.

Invalid UTF-8 byte sequences are replaced with � (U+FFFD). Never feed the result back into a query — use the raw binary or encode/1.

encode(path)

@spec encode(binary()) :: String.t()

A reversible, JSON-safe (valid UTF-8) representation of a Git path.

decode/1 restores the exact original bytes.