or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-parse-github-url

Parse a GitHub URL into an object with repository metadata including owner, name, branch, and file paths.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/parse-github-url@1.0.x

To install, run

npx @tessl/cli install tessl/npm-parse-github-url@1.0.0

index.mddocs/

Parse GitHub URL

Parse GitHub URL is a lightweight Node.js library that parses GitHub URLs into structured objects containing repository metadata. It supports various URL formats including HTTPS, SSH, Git protocols, and GitHub shorthand notation, normalizing them into consistent object structure.

Package Information

  • Package Name: parse-github-url
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install parse-github-url

Core Imports

const parseGithubUrl = require('parse-github-url');

For ES modules:

import parseGithubUrl from 'parse-github-url';

Basic Usage

const parseGithubUrl = require('parse-github-url');

// Parse various GitHub URL formats
const result1 = parseGithubUrl('https://github.com/jonschlinkert/micromatch');
const result2 = parseGithubUrl('git@github.com:jonschlinkert/micromatch.git');
const result3 = parseGithubUrl('jonschlinkert/micromatch#dev');

console.log(result1);
// {
//   owner: 'jonschlinkert',
//   name: 'micromatch', 
//   repo: 'jonschlinkert/micromatch',
//   branch: 'master',
//   host: 'github.com',
//   ...
// }

Capabilities

URL Parsing Function

Parses a GitHub URL string into a structured object with repository metadata.

/**
 * Parse a GitHub URL into an object containing repository information
 * @param {string} str - GitHub URL in any supported format
 * @returns {Object|null} Parsed URL object or null if parsing fails
 */
function parseGithubUrl(str);

The function returns an object with the following properties:

interface ParsedGitHubUrl {
  /** URL protocol (http:, https:, git:, ssh:, etc.) */
  protocol: string | null;
  /** Whether URL has slashes after protocol */
  slashes: boolean | null;
  /** Authentication information from URL */
  auth: string | null;
  /** GitHub host (defaults to 'github.com') */
  host: string;
  /** Port number if specified */
  port: number | null;
  /** Hostname */
  hostname: string | null;
  /** URL hash/fragment */
  hash: string | null;
  /** Search parameters */
  search: string | null;
  /** Query string */
  query: string | null;
  /** URL pathname */
  pathname: string;
  /** URL path */
  path: string;
  /** Full URL */
  href: string;
  /** File path within repository */
  filepath: string | null;
  /** Repository owner/username */
  owner: string | null;
  /** Repository name */
  name: string | null;
  /** Full repository name (owner/name) */
  repo: string | null;
  /** Branch name (defaults to 'master') */
  branch: string;
  /** Alias for repo property */
  repository: string | null;
  /** Blob path for blob URLs */
  blob: string | null;
}

Supported URL Formats:

The function handles various GitHub URL formats:

  • HTTPS: https://github.com/owner/repo
  • HTTP: http://github.com/owner/repo
  • SSH: git@github.com:owner/repo.git
  • Git Protocol: git://github.com/owner/repo.git
  • GitHub Shorthand: owner/repo
  • With Branch: owner/repo#branch-name
  • With Version Tag: owner/repo#v1.0.0
  • Tree URLs: https://github.com/owner/repo/tree/branch
  • Blob URLs: https://github.com/owner/repo/blob/branch/path/to/file
  • File URLs: https://github.com/owner/repo/blob/master/README.md
  • Various Git Hosts: Works with gh.pages.com, github.assemble.com, etc.

Error Handling:

  • Returns null for invalid or unparseable URLs
  • Returns null for Gist URLs (explicitly excluded)
  • Returns null for empty, null, or non-string inputs

Performance:

The function implements internal caching to improve performance for repeated URL parsing of the same URLs.

Command Line Interface

The package includes a CLI tool for parsing GitHub URLs from the command line.

# Parse a GitHub URL and output JSON
parse-github-url <github-url>

# Examples:
parse-github-url "https://github.com/jonschlinkert/micromatch"
parse-github-url "git@github.com:jonschlinkert/micromatch.git" 
parse-github-url "jonschlinkert/micromatch#dev"

Exit Codes:

  • 0: Success - URL parsed successfully
  • 1: Error - Invalid URL or missing argument

Usage Examples:

const parseGithubUrl = require('parse-github-url');

// Parse HTTPS URL
const https = parseGithubUrl('https://github.com/assemble/verb');
console.log(https.owner); // 'assemble'
console.log(https.name);  // 'verb'
console.log(https.repo);  // 'assemble/verb'
console.log(https.branch); // 'master'

// Parse SSH URL
const ssh = parseGithubUrl('git@github.com:assemble/verb.git');
console.log(ssh.owner); // 'assemble'
console.log(ssh.name);  // 'verb'

// Parse shorthand with branch
const shorthand = parseGithubUrl('assemble/verb#dev');
console.log(shorthand.branch); // 'dev'

// Parse file URL
const file = parseGithubUrl('https://github.com/assemble/verb/blob/master/README.md');
console.log(file.filepath); // 'README.md'
console.log(file.branch);   // 'master'

// Parse tree URL
const tree = parseGithubUrl('https://github.com/assemble/verb/tree/feature/docs');
console.log(tree.branch); // 'feature'

// Invalid URLs return null
const invalid = parseGithubUrl('not-a-url');
console.log(invalid); // null

const gist = parseGithubUrl('https://gist.github.com/123456');
console.log(gist); // null (Gists are excluded)