# `Git.Commands.CheckRefFormat`
[🔗](https://github.com/joshrotenberg/git_wrapper_ex/blob/main/lib/git/commands/check_ref_format.ex#L1)

Implements the `Git.Command` behaviour for `git check-ref-format`.

Validates (and optionally normalizes) a ref name. This command uses its exit
code as data: `0` means the ref is well-formed, a non-zero code means it is
not. That signal is translated into `{:ok, _}` / `{:error, :invalid_ref}`
rather than a generic error.

## Modes

  * `:normalize` normalizes the ref and prints it on success
  * `:branch` validates a branch-name shorthand and prints its expansion
  * `:allow_onelevel` accepts single-level refs (e.g. `HEAD`)

# `t`

```elixir
@type t() :: %Git.Commands.CheckRefFormat{
  allow_onelevel: boolean(),
  branch: boolean(),
  normalize: boolean(),
  ref: String.t() | nil
}
```

# `args`

```elixir
@spec args(t()) :: [String.t()]
```

Returns the argument list for `git check-ref-format`.

## Examples

    iex> Git.Commands.CheckRefFormat.args(%Git.Commands.CheckRefFormat{ref: "refs/heads/main"})
    ["check-ref-format", "refs/heads/main"]

    iex> Git.Commands.CheckRefFormat.args(%Git.Commands.CheckRefFormat{ref: "refs/heads//main", normalize: true})
    ["check-ref-format", "--normalize", "refs/heads//main"]

    iex> Git.Commands.CheckRefFormat.args(%Git.Commands.CheckRefFormat{ref: "main", branch: true})
    ["check-ref-format", "--branch", "main"]

    iex> Git.Commands.CheckRefFormat.args(%Git.Commands.CheckRefFormat{ref: "HEAD", allow_onelevel: true})
    ["check-ref-format", "--allow-onelevel", "HEAD"]

# `parse_output`

```elixir
@spec parse_output(String.t(), non_neg_integer()) ::
  {:ok, true | String.t()}
  | {:error, :invalid_ref | {String.t(), non_neg_integer()}}
```

Parses the output of `git check-ref-format`.

- Exit `0` with output (normalize/branch modes) returns `{:ok, normalized}`.
- Exit `0` with no output returns `{:ok, true}`.
- Exit `1` (and the `--branch` invalid-name die at exit `128`) returns
  `{:error, :invalid_ref}`.
- Any other non-zero exit (e.g. a usage error) returns
  `{:error, {stdout, exit_code}}`.

---

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