or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md repository-info.md url-generation.md url-parsing.md

tile.json

Repository Information

Access and manipulate repository metadata including host type, user, project name, and commit references from GitHost instances.

Capabilities

GitHost Instance Properties

Access repository metadata through GitHost instance properties.

/**
 * GitHost instance properties providing repository metadata
 */
interface GitHost {
  /** Host type: 'github', 'gitlab', 'bitbucket', 'gist', 'sourcehut' */
  type: string;
  /** Host domain (e.g., 'github.com', 'gitlab.com') */
  domain: string;
  /** User or organization name */
  user: string;
  /** Repository/project name */
  project: string;
  /** Commit, branch, or tag reference */
  committish: string | null;
  /** Authentication string (username:password or token) */
  auth: string | null;
  /** Default representation type ('shortcut', 'sshurl', 'https', etc.) */
  default: string;
  /** Options object passed during creation */
  opts: object;
}

Usage Examples:

const hostedGitInfo = require("hosted-git-info");

// Parse various URL formats
const info1 = hostedGitInfo.fromUrl("git@github.com:npm/hosted-git-info.git#v1.0.0");
const info2 = hostedGitInfo.fromUrl("https://gitlab.com/user/project.git");
const info3 = hostedGitInfo.fromUrl("gist:abc123def456");

// Access repository metadata
console.log(info1.type);        // "github"
console.log(info1.domain);      // "github.com"
console.log(info1.user);        // "npm"
console.log(info1.project);     // "hosted-git-info"
console.log(info1.committish);  // "v1.0.0"
console.log(info1.auth);        // null

console.log(info2.type);        // "gitlab"
console.log(info2.domain);      // "gitlab.com" 
console.log(info2.user);        // "user"
console.log(info2.project);     // "project"
console.log(info2.committish);  // null

console.log(info3.type);        // "gist"
console.log(info3.domain);      // "gist.github.com"
console.log(info3.user);        // null (for anonymous gists)
console.log(info3.project);     // "abc123def456"

Host Type Detection

Identify the hosting platform from the parsed URL.

const info = hostedGitInfo.fromUrl("https://bitbucket.org/user/repo.git");

switch (info.type) {
  case 'github':
    console.log('GitHub repository');
    break;
  case 'gitlab':
    console.log('GitLab repository');
    break;
  case 'bitbucket':
    console.log('Bitbucket repository');
    break;
  case 'gist':
    console.log('GitHub Gist');
    break;
  case 'sourcehut':
    console.log('Sourcehut repository');
    break;
  default:
    console.log('Unknown host type');
}
// Output: "Bitbucket repository"

Authentication Information

Access authentication credentials embedded in URLs.

// URL with authentication
const info1 = hostedGitInfo.fromUrl("https://user:token@github.com/owner/repo.git");
console.log(info1.auth); // "user:token"

// URL with username only
const info2 = hostedGitInfo.fromUrl("https://user@github.com/owner/repo.git");
console.log(info2.auth); // "user"

// SSH URLs and shortcuts ignore auth in the URL
const info3 = hostedGitInfo.fromUrl("github:user:password@owner/repo");
console.log(info3.auth); // null (auth ignored for shortcuts)

// No authentication
const info4 = hostedGitInfo.fromUrl("https://github.com/owner/repo.git");
console.log(info4.auth); // null

Committish Handling

Work with commit, branch, and tag references.

// URL with branch reference
const info1 = hostedGitInfo.fromUrl("github:npm/hosted-git-info#main");
console.log(info1.committish); // "main"

// URL with tag reference
const info2 = hostedGitInfo.fromUrl("git@github.com:npm/hosted-git-info.git#v1.0.0");
console.log(info2.committish); // "v1.0.0"

// URL with commit hash
const info3 = hostedGitInfo.fromUrl("https://github.com/npm/hosted-git-info.git#abc123def456");
console.log(info3.committish); // "abc123def456"

// No committish
const info4 = hostedGitInfo.fromUrl("github:npm/hosted-git-info");
console.log(info4.committish); // null

// Get hash fragment
console.log(info1.hash()); // "#main"
console.log(info4.hash()); // ""

Default Representation

Understand how the GitHost will represent itself by default.

// Different URL formats have different defaults
const shortcut = hostedGitInfo.fromUrl("github:npm/hosted-git-info");
console.log(shortcut.getDefaultRepresentation()); // "shortcut"
console.log(shortcut.toString()); // "github:npm/hosted-git-info"

const ssh = hostedGitInfo.fromUrl("git@github.com:npm/hosted-git-info.git");
console.log(ssh.getDefaultRepresentation()); // "sshurl"
console.log(ssh.toString()); // "git+ssh://git@github.com/npm/hosted-git-info.git"

const https = hostedGitInfo.fromUrl("https://github.com/npm/hosted-git-info.git");
console.log(https.getDefaultRepresentation()); // "https"
console.log(https.toString()); // "git+https://github.com/npm/hosted-git-info.git"

const extreme = hostedGitInfo.fromUrl("npm/hosted-git-info");
console.log(extreme.getDefaultRepresentation()); // "shortcut"
console.log(extreme.toString()); // "github:npm/hosted-git-info"

Options Object

Access the options that were passed during GitHost creation.

const info = hostedGitInfo.fromUrl("github:npm/hosted-git-info#v1.0.0", {
  noCommittish: true,
  noGitPlus: true,
  customOption: "value"
});

console.log(info.opts);
// Result: { noCommittish: true, noGitPlus: true, customOption: "value" }

// Options affect URL generation
console.log(info.https()); // Uses opts.noGitPlus: true
// Result: "https://github.com/npm/hosted-git-info.git" (no git+ prefix)

Repository Identification Patterns

GitHub Patterns

Domain:
```
github.com
```
User: Organization or username
Project: Repository name (without .git suffix)
Special: Supports extreme shorthand (
```
user/repo
```
)

GitLab Patterns

Domain:
```
gitlab.com
```
(or custom GitLab instances)
User: Can be nested paths (e.g.,
```
group/subgroup
```
)
Project: Repository name
Special: Handles nested group structures

Bitbucket Patterns

Domain:
```
bitbucket.org
```
User: Username or team name
Project: Repository name
Special: Different path structure for browse URLs

GitHub Gist Patterns

Domain:
```
gist.github.com
```
User: May be null for anonymous gists
Project: Gist ID (hexadecimal string)
Special: Different URL generation templates

Sourcehut Patterns

Domain:
```
git.sr.ht
```
User: Username with ~ prefix (e.g.,
```
~username
```
)
Project: Repository name
Special: Limited feature support

Error Conditions

Invalid Repository Information

URLs that cannot be parsed return
```
undefined
```
from
```
fromUrl()
```
Missing required components (user, project) result in parse failure
Malformed URLs are handled gracefully

Missing Properties

Some properties may be
```
null
```
for certain URL types:
- ```
committish
```
  is
```
null
```
  when no branch/tag/commit is specified
- ```
auth
```
  is
```
null
```
  when no authentication is present
- ```
user
```
  may be
```
null
```
  for anonymous gists

Platform Limitations

Not all platforms support all URL generation methods
Some methods may return
```
null
```
for unsupported operations
Host-specific behaviors vary (e.g., Sourcehut has no bugs URL)

Working with Repository Metadata

Repository Comparison

const info1 = hostedGitInfo.fromUrl("github:npm/hosted-git-info#v1.0.0");
const info2 = hostedGitInfo.fromUrl("git@github.com:npm/hosted-git-info.git#v2.0.0");

// Same repository, different versions
const sameRepo = info1.type === info2.type && 
                 info1.user === info2.user && 
                 info1.project === info2.project;
console.log(sameRepo); // true

const sameVersion = info1.committish === info2.committish;
console.log(sameVersion); // false

Metadata Extraction

const info = hostedGitInfo.fromUrl("https://gitlab.com/group/subgroup/project.git#main");

// Extract repository identifier
const repoId = `${info.type}:${info.user}/${info.project}`;
console.log(repoId); // "gitlab:group/subgroup/project"

// Create clone command
const cloneCmd = `git clone ${info.https()}`;
console.log(cloneCmd); // "git clone git+https://gitlab.com/group/subgroup/project.git#main"

// Get web URL for sharing
const webUrl = info.browse();
console.log(webUrl); // "https://gitlab.com/group/subgroup/project/tree/main"