0
# Parse GitHub URL
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: parse-github-url
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install parse-github-url`
10

11
## Core Imports
12

13
```javascript
14
const parseGithubUrl = require('parse-github-url');
15
```
16

17
For ES modules:
18

19
```javascript
20
import parseGithubUrl from 'parse-github-url';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const parseGithubUrl = require('parse-github-url');
27

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

33
console.log(result1);
34
// {
35
//   owner: 'jonschlinkert',
36
//   name: 'micromatch', 
37
//   repo: 'jonschlinkert/micromatch',
38
//   branch: 'master',
39
//   host: 'github.com',
40
//   ...
41
// }
42
```
43

44
## Capabilities
45

46
### URL Parsing Function
47

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

50
```javascript { .api }
51
/**
52
 * Parse a GitHub URL into an object containing repository information
53
 * @param {string} str - GitHub URL in any supported format
54
 * @returns {Object|null} Parsed URL object or null if parsing fails
55
 */
56
function parseGithubUrl(str);
57
```
58

59
The function returns an object with the following properties:
60

61
```javascript { .api }
62
interface ParsedGitHubUrl {
63
  /** URL protocol (http:, https:, git:, ssh:, etc.) */
64
  protocol: string | null;
65
  /** Whether URL has slashes after protocol */
66
  slashes: boolean | null;
67
  /** Authentication information from URL */
68
  auth: string | null;
69
  /** GitHub host (defaults to 'github.com') */
70
  host: string;
71
  /** Port number if specified */
72
  port: number | null;
73
  /** Hostname */
74
  hostname: string | null;
75
  /** URL hash/fragment */
76
  hash: string | null;
77
  /** Search parameters */
78
  search: string | null;
79
  /** Query string */
80
  query: string | null;
81
  /** URL pathname */
82
  pathname: string;
83
  /** URL path */
84
  path: string;
85
  /** Full URL */
86
  href: string;
87
  /** File path within repository */
88
  filepath: string | null;
89
  /** Repository owner/username */
90
  owner: string | null;
91
  /** Repository name */
92
  name: string | null;
93
  /** Full repository name (owner/name) */
94
  repo: string | null;
95
  /** Branch name (defaults to 'master') */
96
  branch: string;
97
  /** Alias for repo property */
98
  repository: string | null;
99
  /** Blob path for blob URLs */
100
  blob: string | null;
101
}
102
```
103

104
**Supported URL Formats:**
105

106
The function handles various GitHub URL formats:
107

108
- **HTTPS**: `https://github.com/owner/repo`
109
- **HTTP**: `http://github.com/owner/repo` 
110
- **SSH**: `git@github.com:owner/repo.git`
111
- **Git Protocol**: `git://github.com/owner/repo.git`
112
- **GitHub Shorthand**: `owner/repo`
113
- **With Branch**: `owner/repo#branch-name`
114
- **With Version Tag**: `owner/repo#v1.0.0`
115
- **Tree URLs**: `https://github.com/owner/repo/tree/branch`
116
- **Blob URLs**: `https://github.com/owner/repo/blob/branch/path/to/file`
117
- **File URLs**: `https://github.com/owner/repo/blob/master/README.md`
118
- **Various Git Hosts**: Works with `gh.pages.com`, `github.assemble.com`, etc.
119

120
**Error Handling:**
121

122
- Returns `null` for invalid or unparseable URLs
123
- Returns `null` for Gist URLs (explicitly excluded)
124
- Returns `null` for empty, null, or non-string inputs
125

126
**Performance:**
127

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

130
### Command Line Interface
131

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

134
```bash { .api }
135
# Parse a GitHub URL and output JSON
136
parse-github-url <github-url>
137

138
# Examples:
139
parse-github-url "https://github.com/jonschlinkert/micromatch"
140
parse-github-url "git@github.com:jonschlinkert/micromatch.git" 
141
parse-github-url "jonschlinkert/micromatch#dev"
142
```
143

144
**Exit Codes:**
145
- `0`: Success - URL parsed successfully
146
- `1`: Error - Invalid URL or missing argument
147

148
**Usage Examples:**
149

150
```javascript
151
const parseGithubUrl = require('parse-github-url');
152

153
// Parse HTTPS URL
154
const https = parseGithubUrl('https://github.com/assemble/verb');
155
console.log(https.owner); // 'assemble'
156
console.log(https.name);  // 'verb'
157
console.log(https.repo);  // 'assemble/verb'
158
console.log(https.branch); // 'master'
159

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

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

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

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

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

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