or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdrepository-info.mdurl-generation.mdurl-parsing.md
tile.json

index.mddocs/

Hosted Git Info

hosted-git-info is a comprehensive URL parsing and transformation library specifically designed for git repositories hosted on popular platforms like GitHub, Bitbucket, GitLab, and Sourcehut. It enables developers to identify, normalize, and convert between different git URL formats and extract structured metadata including host type, domain, user/organization, and project name.

Package Information

  • Package Name: hosted-git-info
  • Package Type: npm
  • Language: JavaScript
  • Installation: 
    npm install hosted-git-info

Core Imports

const hostedGitInfo = require("hosted-git-info");
// or using ES modules
import hostedGitInfo from "hosted-git-info";

Basic Usage

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

// Parse a git URL
const info = hostedGitInfo.fromUrl("git@github.com:npm/hosted-git-info.git");

if (info) {
  console.log(info.type);     // "github"
  console.log(info.domain);   // "github.com"
  console.log(info.user);     // "npm"
  console.log(info.project);  // "hosted-git-info"
  
  // Generate different URL formats
  console.log(info.https());    // "git+https://github.com/npm/hosted-git-info.git"
  console.log(info.ssh());      // "git@github.com:npm/hosted-git-info.git"
  console.log(info.browse());   // "https://github.com/npm/hosted-git-info"
}

Architecture

hosted-git-info is built around several key components:

  • GitHost Class: Core class that represents a parsed git repository with methods for URL generation
  • URL Parsing: Robust parsing logic that handles various git URL formats and edge cases
  • Host Configurations: Platform-specific templates and extraction logic for GitHub, GitLab, Bitbucket, Gist, and Sourcehut
  • Caching: LRU cache for improved performance when parsing frequently used URLs
  • Template System: Flexible template-based URL generation for different output formats

Capabilities

URL Parsing and Creation

Parse git URLs and create GitHost instances that provide access to repository metadata and URL transformation methods.

/**
 * Parse a git URL and return a GitHost instance
 * @param {string} giturl - Git URL to parse
 * @param {object} [opts] - Options object
 * @param {boolean} [opts.noCommittish] - Exclude committish from generated URLs
 * @param {boolean} [opts.noGitPlus] - Exclude 'git+' prefix from URLs
 * @returns {GitHost|undefined} GitHost instance or undefined if URL cannot be parsed
 */
static fromUrl(giturl, opts);

/**
 * Parse repository URL from package manifest
 * @param {object} manifest - Package manifest object
 * @param {object} [opts] - Options object
 * @returns {GitHost|string|null} GitHost instance, URL string, or null
 */
static fromManifest(manifest, opts);

/**
 * Parse URL into components
 * @param {string} url - URL to parse
 * @returns {object} Parsed URL object
 */
static parseUrl(url);

URL Parsing and Creation

URL Format Generation

Generate different URL formats for git operations, browsing, file access, and downloads from a parsed GitHost instance.

/**
 * Generate SSH format URL
 * @param {object} [opts] - Options object
 * @returns {string} SSH URL (e.g., 'git@github.com:user/repo.git')
 */
ssh(opts);

/**
 * Generate HTTPS git URL
 * @param {object} [opts] - Options object  
 * @returns {string} HTTPS URL (e.g., 'git+https://github.com/user/repo.git')
 */
https(opts);

/**
 * Generate browsable web URL
 * @param {string} [path] - Optional path within repository
 * @param {string} [fragment] - Optional fragment/anchor
 * @param {object} [opts] - Options object
 * @returns {string} Browse URL (e.g., 'https://github.com/user/repo')
 */
browse(path, fragment, opts);

/**
 * Generate raw file access URL
 * @param {string} path - Path to file within repository
 * @param {object} [opts] - Options object
 * @returns {string} Raw file URL
 */
file(path, opts);

URL Format Generation

Repository Information

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

/**
 * GitHost instance properties
 */
interface GitHost {
  /** Host type: 'github', 'gitlab', 'bitbucket', 'gist', 'sourcehut' */
  type: string;
  /** Host domain (e.g., 'github.com') */
  domain: string;
  /** User or organization name */
  user: string;
  /** Repository/project name */
  project: string;
  /** Commit, branch, or tag reference */
  committish: string | null;
  /** Authentication string */
  auth: string | null;
  /** Default representation type */
  default: string;
  /** Options object */
  opts: object;
}

Repository Information

Types

/**
 * Complete GitHost class interface with all methods and properties
 */
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 */
  default: string;
  /** Options object passed during creation */
  opts: object;

  // URL Generation Methods
  /** Generate SSH format URL */
  ssh(opts?: Options): string;
  /** Generate SSH URL with git+ssh protocol */
  sshurl(opts?: Options): string;
  /** Generate HTTPS git URL */
  https(opts?: Options): string;
  /** Generate git protocol URL */
  git(opts?: Options): string;
  /** Generate browsable web URL */
  browse(path?: string, fragment?: string, opts?: Options): string;
  /** Generate browsable web URL for a specific file */
  browseFile(path: string, fragment?: string, opts?: Options): string;
  /** Generate raw file access URL */
  file(path: string, opts?: Options): string;
  /** Generate file edit URL */
  edit(path: string, opts?: Options): string;
  /** Generate documentation URL */
  docs(opts?: Options): string;
  /** Generate issues/bugs URL */
  bugs(opts?: Options): string;
  /** Generate shortcut format */
  shortcut(opts?: Options): string;
  /** Generate path format */
  path(opts?: Options): string;
  /** Generate tarball download URL */
  tarball(opts?: Options): string;

  // Utility Methods
  /** Get hash fragment for committish */
  hash(): string;
  /** Get default representation type */
  getDefaultRepresentation(): string;
  /** Get string representation using default format */
  toString(opts?: Options): string;

  // Static Methods
  /** Parse a git URL and return a GitHost instance */
  static fromUrl(giturl: string, opts?: Options): GitHost | undefined;
  /** Parse repository URL from package manifest */
  static fromManifest(manifest: Manifest, opts?: Options): GitHost | string | null;
  /** Parse URL into components */
  static parseUrl(url: string): object | undefined;
  /** Add a custom host configuration */
  static addHost(name: string, host: HostConfiguration): void;
}

/**
 * Options object for GitHost methods
 */
interface Options {
  /** Exclude committish from generated URLs */
  noCommittish?: boolean;
  /** Exclude 'git+' prefix from URLs */
  noGitPlus?: boolean;
  /** Custom path for URL generation */
  path?: string;
}

/**
 * Package manifest object structure
 */
interface Manifest {
  /** Repository field - can be string or object */
  repository?: string | {
    /** Repository URL */
    url: string;
    /** Repository type (usually 'git') */
    type?: string;
  };
}

/**
 * Host configuration object for custom git hosts
 */
interface HostConfiguration {
  /** Supported protocols for this host */
  protocols: string[];
  /** Primary domain for the host */
  domain: string;
  /** Path segment for tree/directory browsing */
  treepath?: string;
  /** Path segment for blob/file browsing */
  blobpath?: string;
  /** Path segment for file editing */
  editpath?: string;
  /** Template function for HTTPS URLs */
  httpstemplate?: (params: TemplateParams) => string;
  /** Template function for SSH URLs */
  sshtemplate?: (params: TemplateParams) => string;
  /** Template function for git protocol URLs */
  gittemplate?: (params: TemplateParams) => string;
  /** Template function for browse URLs */
  browsetemplate?: (params: TemplateParams) => string;
  /** Template function for file URLs */
  filetemplate?: (params: TemplateParams) => string;
  /** Template function for edit URLs */
  edittemplate?: (params: TemplateParams) => string;
  /** Template function for documentation URLs */
  docstemplate?: (params: TemplateParams) => string;
  /** Template function for bugs/issues URLs */
  bugstemplate?: (params: TemplateParams) => string;
  /** Template function for tarball URLs */
  tarballtemplate?: (params: TemplateParams) => string;
  /** Template function for shortcut format */
  shortcuttemplate?: (params: TemplateParams) => string;
  /** Template function for path format */
  pathtemplate?: (params: TemplateParams) => string;
  /** Function to extract repository info from parsed URL */
  extract: (url: URL) => ExtractResult | null;
  /** Function to format hash fragments */
  hashformat?: (fragment: string) => string;
}

/**
 * Parameters passed to template functions
 */
interface TemplateParams {
  /** Host type */
  type?: string;
  /** Host domain */
  domain?: string;
  /** User or organization name */
  user?: string;
  /** Repository/project name */
  project?: string;
  /** Commit, branch, or tag reference */
  committish?: string;
  /** Authentication string */
  auth?: string;
  /** File path */
  path?: string;
  /** Fragment/anchor */
  fragment?: string;
  /** Tree path segment */
  treepath?: string;
  /** Blob path segment */
  blobpath?: string;
  /** Edit path segment */
  editpath?: string;
  /** Hash formatting function */
  hashformat?: (fragment: string) => string;
}

/**
 * Result of URL extraction for custom hosts
 */
interface ExtractResult {
  /** User or organization name */
  user?: string;
  /** Repository/project name */
  project: string;
  /** Commit, branch, or tag reference */
  committish?: string;
}