CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-hosted-git-info

Provides metadata and conversions from repository urls for GitHub, Bitbucket and GitLab

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

repository-info.mddocs/

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"

docs

index.md

repository-info.md

url-generation.md

url-parsing.md

tile.json