# `Minga.Project.FileRef`
[🔗](https://github.com/jsmestad/minga/blob/main/lib/minga/project/file_ref.ex#L1)

Logical file identity for workspace membership.

A file ref identifies the user's logical file, not a future backend or overlay path. Path refs are scoped to an expanded project root plus a normalized relative path. Buffer refs identify unsaved or special buffers by their live buffer pid.

# `kind`

```elixir
@type kind() :: :path | :buffer
```

# `t`

```elixir
@type t() :: %Minga.Project.FileRef{
  buffer_pid: pid() | nil,
  display_name: String.t(),
  kind: kind(),
  project_root: String.t() | nil,
  relative_path: String.t() | nil
}
```

# `display_label`

```elixir
@spec display_label(t()) :: String.t()
```

Returns the display label for a file ref.

# `equal?`

```elixir
@spec equal?(t() | nil, t() | nil) :: boolean()
```

Returns true when two refs identify the same logical file.

# `from_buffer`

```elixir
@spec from_buffer(pid()) :: t()
```

Builds a buffer-backed logical file ref for an unsaved or special buffer.

# `from_file_path`

```elixir
@spec from_file_path(String.t()) :: t()
```

Builds a path-backed file ref for an arbitrary filesystem path.

# `from_path`

```elixir
@spec from_path(String.t(), String.t()) :: {:ok, t()} | {:error, :outside_project}
```

Builds a path-backed logical file ref scoped to a project root.

---

*Consult [api-reference.md](api-reference.md) for complete listing*