0
# Hosted Git Info
1

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

4
## Package Information
5

6
- **Package Name**: hosted-git-info
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install hosted-git-info`
10

11
## Core Imports
12

13
```javascript
14
const hostedGitInfo = require("hosted-git-info");
15
// or using ES modules
16
import hostedGitInfo from "hosted-git-info";
17
```
18

19
## Basic Usage
20

21
```javascript
22
const hostedGitInfo = require("hosted-git-info");
23

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

27
if (info) {
28
  console.log(info.type);     // "github"
29
  console.log(info.domain);   // "github.com"
30
  console.log(info.user);     // "npm"
31
  console.log(info.project);  // "hosted-git-info"
32
  
33
  // Generate different URL formats
34
  console.log(info.https());    // "git+https://github.com/npm/hosted-git-info.git"
35
  console.log(info.ssh());      // "git@github.com:npm/hosted-git-info.git"
36
  console.log(info.browse());   // "https://github.com/npm/hosted-git-info"
37
}
38
```
39

40
## Architecture
41

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

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

50
## Capabilities
51

52
### URL Parsing and Creation
53

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

56
```javascript { .api }
57
/**
58
 * Parse a git URL and return a GitHost instance
59
 * @param {string} giturl - Git URL to parse
60
 * @param {object} [opts] - Options object
61
 * @param {boolean} [opts.noCommittish] - Exclude committish from generated URLs
62
 * @param {boolean} [opts.noGitPlus] - Exclude 'git+' prefix from URLs
63
 * @returns {GitHost|undefined} GitHost instance or undefined if URL cannot be parsed
64
 */
65
static fromUrl(giturl, opts);
66

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

75
/**
76
 * Parse URL into components
77
 * @param {string} url - URL to parse
78
 * @returns {object} Parsed URL object
79
 */
80
static parseUrl(url);
81
```
82

83
[URL Parsing and Creation](./url-parsing.md)
84

85
### URL Format Generation
86

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

89
```javascript { .api }
90
/**
91
 * Generate SSH format URL
92
 * @param {object} [opts] - Options object
93
 * @returns {string} SSH URL (e.g., 'git@github.com:user/repo.git')
94
 */
95
ssh(opts);
96

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

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

113
/**
114
 * Generate raw file access URL
115
 * @param {string} path - Path to file within repository
116
 * @param {object} [opts] - Options object
117
 * @returns {string} Raw file URL
118
 */
119
file(path, opts);
120
```
121

122
[URL Format Generation](./url-generation.md)
123

124
### Repository Information
125

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

128
```javascript { .api }
129
/**
130
 * GitHost instance properties
131
 */
132
interface GitHost {
133
  /** Host type: 'github', 'gitlab', 'bitbucket', 'gist', 'sourcehut' */
134
  type: string;
135
  /** Host domain (e.g., 'github.com') */
136
  domain: string;
137
  /** User or organization name */
138
  user: string;
139
  /** Repository/project name */
140
  project: string;
141
  /** Commit, branch, or tag reference */
142
  committish: string | null;
143
  /** Authentication string */
144
  auth: string | null;
145
  /** Default representation type */
146
  default: string;
147
  /** Options object */
148
  opts: object;
149
}
150
```
151

152
[Repository Information](./repository-info.md)
153

154
## Types
155

156
```javascript { .api }
157
/**
158
 * Complete GitHost class interface with all methods and properties
159
 */
160
interface GitHost {
161
  /** Host type: 'github', 'gitlab', 'bitbucket', 'gist', 'sourcehut' */
162
  type: string;
163
  /** Host domain (e.g., 'github.com', 'gitlab.com') */
164
  domain: string;
165
  /** User or organization name */
166
  user: string;
167
  /** Repository/project name */
168
  project: string;
169
  /** Commit, branch, or tag reference */
170
  committish: string | null;
171
  /** Authentication string (username:password or token) */
172
  auth: string | null;
173
  /** Default representation type */
174
  default: string;
175
  /** Options object passed during creation */
176
  opts: object;
177

178
  // URL Generation Methods
179
  /** Generate SSH format URL */
180
  ssh(opts?: Options): string;
181
  /** Generate SSH URL with git+ssh protocol */
182
  sshurl(opts?: Options): string;
183
  /** Generate HTTPS git URL */
184
  https(opts?: Options): string;
185
  /** Generate git protocol URL */
186
  git(opts?: Options): string;
187
  /** Generate browsable web URL */
188
  browse(path?: string, fragment?: string, opts?: Options): string;
189
  /** Generate browsable web URL for a specific file */
190
  browseFile(path: string, fragment?: string, opts?: Options): string;
191
  /** Generate raw file access URL */
192
  file(path: string, opts?: Options): string;
193
  /** Generate file edit URL */
194
  edit(path: string, opts?: Options): string;
195
  /** Generate documentation URL */
196
  docs(opts?: Options): string;
197
  /** Generate issues/bugs URL */
198
  bugs(opts?: Options): string;
199
  /** Generate shortcut format */
200
  shortcut(opts?: Options): string;
201
  /** Generate path format */
202
  path(opts?: Options): string;
203
  /** Generate tarball download URL */
204
  tarball(opts?: Options): string;
205

206
  // Utility Methods
207
  /** Get hash fragment for committish */
208
  hash(): string;
209
  /** Get default representation type */
210
  getDefaultRepresentation(): string;
211
  /** Get string representation using default format */
212
  toString(opts?: Options): string;
213

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

225
/**
226
 * Options object for GitHost methods
227
 */
228
interface Options {
229
  /** Exclude committish from generated URLs */
230
  noCommittish?: boolean;
231
  /** Exclude 'git+' prefix from URLs */
232
  noGitPlus?: boolean;
233
  /** Custom path for URL generation */
234
  path?: string;
235
}
236

237
/**
238
 * Package manifest object structure
239
 */
240
interface Manifest {
241
  /** Repository field - can be string or object */
242
  repository?: string | {
243
    /** Repository URL */
244
    url: string;
245
    /** Repository type (usually 'git') */
246
    type?: string;
247
  };
248
}
249

250
/**
251
 * Host configuration object for custom git hosts
252
 */
253
interface HostConfiguration {
254
  /** Supported protocols for this host */
255
  protocols: string[];
256
  /** Primary domain for the host */
257
  domain: string;
258
  /** Path segment for tree/directory browsing */
259
  treepath?: string;
260
  /** Path segment for blob/file browsing */
261
  blobpath?: string;
262
  /** Path segment for file editing */
263
  editpath?: string;
264
  /** Template function for HTTPS URLs */
265
  httpstemplate?: (params: TemplateParams) => string;
266
  /** Template function for SSH URLs */
267
  sshtemplate?: (params: TemplateParams) => string;
268
  /** Template function for git protocol URLs */
269
  gittemplate?: (params: TemplateParams) => string;
270
  /** Template function for browse URLs */
271
  browsetemplate?: (params: TemplateParams) => string;
272
  /** Template function for file URLs */
273
  filetemplate?: (params: TemplateParams) => string;
274
  /** Template function for edit URLs */
275
  edittemplate?: (params: TemplateParams) => string;
276
  /** Template function for documentation URLs */
277
  docstemplate?: (params: TemplateParams) => string;
278
  /** Template function for bugs/issues URLs */
279
  bugstemplate?: (params: TemplateParams) => string;
280
  /** Template function for tarball URLs */
281
  tarballtemplate?: (params: TemplateParams) => string;
282
  /** Template function for shortcut format */
283
  shortcuttemplate?: (params: TemplateParams) => string;
284
  /** Template function for path format */
285
  pathtemplate?: (params: TemplateParams) => string;
286
  /** Function to extract repository info from parsed URL */
287
  extract: (url: URL) => ExtractResult | null;
288
  /** Function to format hash fragments */
289
  hashformat?: (fragment: string) => string;
290
}
291

292
/**
293
 * Parameters passed to template functions
294
 */
295
interface TemplateParams {
296
  /** Host type */
297
  type?: string;
298
  /** Host domain */
299
  domain?: string;
300
  /** User or organization name */
301
  user?: string;
302
  /** Repository/project name */
303
  project?: string;
304
  /** Commit, branch, or tag reference */
305
  committish?: string;
306
  /** Authentication string */
307
  auth?: string;
308
  /** File path */
309
  path?: string;
310
  /** Fragment/anchor */
311
  fragment?: string;
312
  /** Tree path segment */
313
  treepath?: string;
314
  /** Blob path segment */
315
  blobpath?: string;
316
  /** Edit path segment */
317
  editpath?: string;
318
  /** Hash formatting function */
319
  hashformat?: (fragment: string) => string;
320
}
321

322
/**
323
 * Result of URL extraction for custom hosts
324
 */
325
interface ExtractResult {
326
  /** User or organization name */
327
  user?: string;
328
  /** Repository/project name */
329
  project: string;
330
  /** Commit, branch, or tag reference */
331
  committish?: string;
332
}
333
```