or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-git-url-parse

A high level git url parser for common git providers.

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/git-url-parse@16.1.x

To install, run

npx @tessl/cli install tessl/npm-git-url-parse@16.1.0

Git URL Parse

Git URL Parse is a high-level Git URL parser specifically designed for common Git providers like GitHub, GitLab, Bitbucket, Azure DevOps, and others. It can parse various Git URL formats (SSH, HTTPS, shorthand) and extract meaningful information including repository owner, name, branch references, file paths, and provider-specific details.

Package Information

Package Name: git-url-parse
Package Type: npm
Language: JavaScript (with TypeScript definitions)
Installation: npm install git-url-parse

Core Imports

const gitUrlParse = require("git-url-parse");

For ES modules:

import gitUrlParse from "git-url-parse";

Basic Usage

const gitUrlParse = require("git-url-parse");

// Parse a GitHub SSH URL
const parsed = gitUrlParse("git@github.com:IonicaBizau/git-url-parse.git");
console.log(parsed.owner);    // "IonicaBizau"
console.log(parsed.name);     // "git-url-parse"
console.log(parsed.source);   // "github.com"

// Parse an HTTPS URL with file path
const fileUrl = gitUrlParse("https://github.com/owner/repo/blob/master/src/index.js");
console.log(fileUrl.ref);           // "master"
console.log(fileUrl.filepath);      // "src/index.js"
console.log(fileUrl.filepathtype);  // "blob"

// Convert between URL formats
const httpsUrl = parsed.toString("https");
const sshUrl = parsed.toString("ssh");

Architecture

Git URL Parse is built around a single parsing function that:

URL Recognition: Detects Git hosting providers and URL patterns
Provider-Specific Logic: Handles unique URL structures for different hosts
Property Extraction: Extracts structured data from complex URL patterns
Format Conversion: Enables conversion between SSH, HTTPS, and other protocols
Branch/File Parsing: Supports complex branch names and file path extraction

Capabilities

URL Parsing

Core Git URL parsing functionality that extracts comprehensive metadata from various Git URL formats.

/**
 * Parses a Git URL and extracts structured information
 * @param {string} url - The Git URL to parse
 * @param {string[]} [refs] - Optional array of branch names for complex parsing
 * @returns {GitUrl} Parsed Git URL object with metadata
 * @throws {Error} When url is not a string or refs contain non-strings
 */
function gitUrlParse(url, refs?);

URL Stringification

Converts a parsed GitUrl object back to a URL string in various formats.

/**
 * Stringifies a GitUrl object to a URL string
 * @param {GitUrl} obj - The parsed Git URL object
 * @param {string} [type] - Target URL format (ssh, https, git+ssh, etc.)
 * @returns {string} Formatted Git URL string
 */
gitUrlParse.stringify(obj, type?);

// Also available as instance method
gitUrlObject.toString(type?);

Types

GitUrl Object

The main object returned by the parsing function, containing comprehensive Git URL metadata.

interface GitUrl {
  // Core URL properties (from git-up ParsedUrl)
  protocols: string[];           // Array of URL protocols
  port: string | null;           // Domain port
  resource: string;              // URL domain including subdomains
  user: string;                  // Authentication user (for SSH URLs)
  password: string;              // Authentication password (for basic auth URLs)
  pathname: string;              // URL pathname
  hash: string;                  // URL hash
  search: string;                // URL querystring value
  query: object;                 // Parsed querystring as object
  href: string;                  // Original input URL
  protocol: string;              // Primary Git URL protocol
  token: string;                 // OAuth token (for HTTPS URLs)
  
  // Git-specific properties
  source: string;                // Git provider (e.g., "github.com")
  owner: string;                 // Repository owner/username
  name: string;                  // Repository name
  ref: string;                   // Repository ref/branch (e.g., "master")
  filepath: string;              // File path relative to repository root
  filepathtype: string;          // Type of filepath ("blob", "tree", "raw", "src", "edit")
  full_name: string;             // Owner and name in "owner/name" format
  organization: string;          // Organization the owner belongs to
  git_suffix: boolean;           // Whether to add ".git" suffix
  commit?: string;               // Commit hash (for commit URLs)
  
  // Methods
  toString(type?: string): string;  // Convert to URL string format
}

Supported Providers

Git URL Parse supports the following Git hosting providers:

Standard Providers

GitHub (github.com) - Including gists and enterprise
GitLab (gitlab.com) - Including subgroups and self-hosted
Bitbucket Cloud (bitbucket.org) - Including personal repositories
Bitbucket Server - On-premise installations

Enterprise/Cloud Providers

Azure DevOps (dev.azure.com, azure.com)
Visual Studio Team Services (visualstudio.com)
CloudForge (cloudforge.com)
Custom Git hosting services

URL Format Support

SSH URLs: git@host:owner/repo.git
HTTPS URLs: https://host/owner/repo.git
Git+SSH URLs: git+ssh://user@host/owner/repo.git
FTP/FTPS URLs: ftp://host/owner/repo.git
Shorthand URLs: owner/repo (defaults to GitHub)
URLs with authentication tokens
URLs with file paths and branch references
URLs with URL-encoded characters

Usage Examples

Parsing Different URL Formats

const gitUrlParse = require("git-url-parse");

// SSH format
const sshUrl = gitUrlParse("git@github.com:owner/repo.git");
console.log(sshUrl.protocol);  // "ssh"
console.log(sshUrl.user);      // "git"

// HTTPS format
const httpsUrl = gitUrlParse("https://github.com/owner/repo.git");
console.log(httpsUrl.protocol);  // "https"

// With authentication
const authUrl = gitUrlParse("https://token:x-oauth-basic@github.com/owner/repo.git");
console.log(authUrl.token);  // "token"

// Shorthand (GitHub)
const shortUrl = gitUrlParse("owner/repo");
console.log(shortUrl.source);  // "github.com"
console.log(shortUrl.href);    // "https://github.com/owner/repo"

Working with File Paths and Branches

// GitHub blob URL
const fileUrl = gitUrlParse("https://github.com/owner/repo/blob/main/src/index.js");
console.log(fileUrl.ref);           // "main"
console.log(fileUrl.filepath);      // "src/index.js"
console.log(fileUrl.filepathtype);  // "blob"

// Complex branch names (requires refs parameter)
const complexBranch = gitUrlParse(
  "https://github.com/owner/repo/blob/feature/new-parser/README.md",
  ["feature/new-parser", "main"]
);
console.log(complexBranch.ref);      // "feature/new-parser"
console.log(complexBranch.filepath); // "README.md"

Converting Between Formats

const gitUrlParse = require("git-url-parse");
const parsed = gitUrlParse("git@github.com:owner/repo.git");

// Convert to different formats using instance method
console.log(parsed.toString("https"));    // "https://github.com/owner/repo.git"
console.log(parsed.toString("ssh"));      // "git@github.com:owner/repo.git"
console.log(parsed.toString("git+ssh"));  // "git+ssh://git@github.com/owner/repo.git"

// Using static method (same results)
console.log(gitUrlParse.stringify(parsed, "https"));  // "https://github.com/owner/repo.git"
console.log(gitUrlParse.stringify(parsed, "ssh"));    // "git@github.com:owner/repo.git"
console.log(gitUrlParse.stringify(parsed, "git+ssh"));// "git+ssh://git@github.com/owner/repo.git"

Provider-Specific Features

// Azure DevOps with organization
const azureUrl = gitUrlParse("https://dev.azure.com/MyOrg/MyProject/_git/MyRepo");
console.log(azureUrl.source);       // "azure.com"
console.log(azureUrl.organization); // "MyOrg"
console.log(azureUrl.owner);        // "MyProject"
console.log(azureUrl.name);         // "MyRepo"

// GitLab subgroups
const gitlabUrl = gitUrlParse("https://gitlab.com/group/subgroup/project");
console.log(gitlabUrl.owner);       // "group/subgroup"
console.log(gitlabUrl.name);        // "project"

// Bitbucket Server
const bitbucketUrl = gitUrlParse("https://bitbucket.company.com/projects/PROJ/repos/repo");
console.log(bitbucketUrl.source);   // "bitbucket-server"
console.log(bitbucketUrl.owner);    // "PROJ"
console.log(bitbucketUrl.name);     // "repo"

// Commit URLs
const commitUrl = gitUrlParse("https://github.com/owner/repo/commit/9c6443245ace92d237b7b274d4606a616e071c4e");
console.log(commitUrl.commit);      // "9c6443245ace92d237b7b274d4606a616e071c4e"
console.log(commitUrl.owner);       // "owner"
console.log(commitUrl.name);        // "repo"

Error Handling

The parser throws standard JavaScript Error objects in specific cases:

const gitUrlParse = require("git-url-parse");

try {
  // Invalid input type - url must be a string
  gitUrlParse(123);  // Throws: Error("The url must be a string.")
} catch (error) {
  console.error(error.message);  // "The url must be a string."
}

try {
  // Invalid refs parameter - all refs must be strings
  gitUrlParse("git@github.com:owner/repo.git", [123, "main"]);  
  // Throws: Error("The refs should contain only strings")
} catch (error) {
  console.error(error.message);  // "The refs should contain only strings"
}

// Valid examples that don't throw errors
const valid1 = gitUrlParse("git@github.com:owner/repo.git");  // ✓
const valid2 = gitUrlParse("invalid-url");  // ✓ Still parses, may have unexpected results
const valid3 = gitUrlParse("https://github.com/owner/repo", ["main", "dev"]);  // ✓