IF Commons GitHub

remote

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-githost FR-007

A Git remote URL read as a repository on a host (commons 0001-githost FR-005, FR-007, FR-008): the https, git://, ssh:// and scp-like (git@host:owner/repo) forms give the same RepoRef, whichever way the remote is written, so that a clone made over SSH is the repository the manifest names over HTTPS.

A credential in the URL (https://user:token@host/...) is dropped: no result, no error and no message holds it. The host name is lower-cased and its port is dropped (an SSH port and an HTTPS port say how to reach a host, not which repository it is); the path is kept as the host writes it, without .git and without a trailing slash. The kind of host is GitHub for github.com, GitLab for gitlab.com and for a host a map names, and plain Git for every other: a self-managed GitLab is named, never guessed from a URL (FR-019).

Source: commons/githost/src/remote.ts

6 of 10 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

cloneUrlOffunction
function cloneUrlOf(ref: RepoRef): string

The HTTPS URL a repository is cloned from, with no credential in it.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

describeReffunctionno test imports it
function describeRef(ref: RepoRef): string

A repository as host/owner/repo: the name used in messages, never a URL with a credential.

describeRemoteErrorfunction
function describeRemoteError(e: RemoteError): string

A remote error as one sentence.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

hostKindOffunction
function hostKindOf(host: string, hostKinds?: Readonly<Record<string, HostKind>>): HostKind

The kind of a host: GitHub for github.com, GitLab for gitlab.com, what the map says for a host it names, and plain Git for every other (0001-githost FR-005).

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

HostKindstypeno test imports it
type HostKinds = Readonly<Record<string, HostKind>>;

The hosts that are not plain Git, by name: a map from a lower-case host name to its kind, as the manifest names them (a self-managed GitLab, or GitHub Enterprise Server).

parseRemotefunction
function parseRemote(url: string, hostKinds?: Readonly<Record<string, HostKind>>): Result<RepoRef, RemoteError>

A remote URL as the repository it names. The forms: https://host/path(.git), http://, git://, ssh://[user@]host[:port]/path(.git) and [user@]host:path(.git). A credential in the URL is dropped; hostKinds names the hosts that are not plain Git.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

readRemotefunction
function readRemote(input: string, hostKinds?: Readonly<Record<string, HostKind>>): Result<ReadRemote, RemoteError>

A remote as a person writes it, where the domain says the rest: github.com/owner/repo and gitlab.example.com/group/sub/repo need no https://, owner/repo is a repository of GitHub, github:owner/repo and gitlab:group/sub/repo name the host's kind, and the address of a branch's page (.../tree/main) is the repository and that branch. Every form parseRemote reads is read as it does. A text that begins with /, . or ~, a Windows drive or a file: URL is a path on this computer and an error, as it is there.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

ReadRemotetypeno test imports it
type ReadRemote = { readonly ref: RepoRef; readonly branch?: string };

A remote as a person writes it: the repository, and the branch where the text is the address of a branch's page.

RemoteErrortypeno test imports it
type RemoteError =
  | { readonly kind: "empty" }
  | { readonly kind: "local-path" }
  | { readonly kind: "unsupported-scheme"; readonly scheme: string }
  | { readonly kind: "no-host" }
  | { readonly kind: "no-path" }
  | { readonly kind: "bad-segment"; readonly reason: string };

Why a text is not a remote URL of a repository on a host. Never holds the URL, which may hold a credential.

sameRepositoryfunction
function sameRepository(a: RepoRef, b: RepoRef): boolean

Whether two references name the same repository: the same host, and paths equal by their case (GitHub and GitLab paths are not case-sensitive).

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.