module Git::Repository::Branching::Private

Builds the full git ref string from a branch name argument

Mirrors the routing logic of ‘Git::Branch#update_ref` for backward compatibility:

• ‘remotes/<remote>/<name>` or `refs/remotes/<remote>/<name>` →`refs/remotes/<remote>/<name>`

• Any other value → ‘refs/heads/<branch>`

@param branch [String] a short local branch name or a remote-tracking

branch name with a `remotes/` or `refs/remotes/` prefix

@return [String] the full git ref string

@api private

Determines whether the given branch ref points to an existing commit

Returns ‘:active` when the branch ref resolves successfully. Returns `:unborn` when the branch ref exists but has no commits yet (exit status 1 with empty stderr from `git rev-parse –verify –quiet`). Re-raises for any other failure.

@param execution_context [Git::ExecutionContext::Repository] the

execution context for git commands

@param branch_name [String] the branch name to verify

@return [:active, :unborn] the branch ref state

@raise [Git::FailedError] if git exits with a failure unrelated to an

unborn branch

@api private

Normalizes the ‘:orphan` option, rejecting names that git would never see

‘:orphan` is a value option on the underlying command, so a literal `false` would be emitted as `–orphan false` and create a branch named “false”. Flag options such as `:force` already ignore `false`; this gives `:orphan` the same behavior.

A blank name is rejected rather than dropped: the argument DSL omits empty values, so ‘orphan: ”` would otherwise degrade silently into a plain checkout.

@param checkout_options [Hash] the raw options passed to {#checkout}

@return [Hash] the options with a ‘false` `:orphan` key removed

@raise [ArgumentError] if ‘:orphan` is given a blank branch name

@api private

Normalizes path specifications for Git commands

@param pathspecs [String, Pathname, Array<String, Pathname>, nil]

the path(s) to normalize

@param arg_name [String] the argument name used in error messages

@return [Array<String>, nil] the normalized paths, or ‘nil` if none are valid

@raise [ArgumentError] when any path is not a ‘String` or `Pathname`

@api private

Translates {#checkout} options to the new command interface

Legacy callers passed combinations like:

checkout('branch', new_branch: true, start_point: 'main')

which should map to:

checkout('main', b: 'branch')

‘orphan: true` follows the same shape, naming the unborn branch:

checkout('branch', orphan: true, start_point: 'main')

maps to:

checkout('main', orphan: 'branch')

@param branch [String, nil] the branch argument passed to {#checkout}

@param checkout_options [Hash] the raw options passed to {#checkout}

@return [Array((String, nil), Hash)] a two-element tuple

`[target, options]` containing the translated checkout arguments

`target` (`String` or `nil`) is the branch or commit to check out.
`options` is a `Hash` of keyword arguments for
`Git::Commands::Checkout::Branch#call`

@api private

Translates ‘orphan: true` into the command’s ‘:orphan` value option

‘orphan: true` names the unborn branch from the positional argument and takes its start point from `:start_point`, mirroring `new_branch: true`.

@param branch [String, nil] the branch argument passed to {#checkout}

@param checkout_options [Hash] the raw options passed to {#checkout}

@return [Array((String, nil), Hash)] a two-element tuple

`[target, options]` containing the translated checkout arguments

@raise [ArgumentError] if ‘branch` is blank (`nil`, empty, or whitespace

only), since the unborn branch would otherwise have no name

@api private

Raises an error if any element of ‘pathspecs` is not a `String` or `Pathname`

@param pathspecs [Array] the path elements to validate

@param arg_name [String] the argument name used in error messages

@return [void]

@raise [ArgumentError] when any element is not a ‘String` or `Pathname`

@api private