Shared modules of the Helix Project - Git Utils
npm install @adobe/helix-shared-gitThe GitUrl class provides utilities for parsing, manipulating, and working with Git repository URLs across various formats including HTTP/HTTPS, SSH, and SCP-style URLs.
``bash`
npm install @adobe/helix-shared-git
The GitUrl class can parse standard Git URLs and extract repository information:
`js
import { GitUrl } from '@adobe/helix-shared-git';
// Parse a standard Git URL
const url = new GitUrl('https://github.com/adobe/helix-shared.git#main');
console.log(url.protocol); // 'https'
console.log(url.hostname); // 'github.com'
console.log(url.owner); // 'adobe'
console.log(url.repo); // 'helix-shared'
console.log(url.ref); // 'main'
console.log(url.path); // ''
`
You can also create a GitUrl from an object representation:
`js
const url = new GitUrl({
owner: 'adobe',
repo: 'helix-shared',
ref: 'main',
path: '/packages'
});
console.log(url.toString());
// 'https://github.com/adobe/helix-shared.git/packages#main'
`
The GitUrl class supports multiple Git URL formats:
`js
// Standard HTTPS URL
const httpsUrl = new GitUrl('https://github.com/adobe/helix-shared.git#main');
// SSH URL
const sshUrl = new GitUrl('ssh://git@github.com/adobe/helix-shared.git#main');
// SCP-style Git URL (commonly used with git clone)
const scpUrl = new GitUrl('git@github.com:adobe/helix-shared.git#main');
// Self-hosted Git server with custom port
const customUrl = new GitUrl('https://git.example.com:8080/company/repo.git#develop');
`
The GitUrl class provides convenient properties for accessing raw content and API endpoints:
`js
const url = new GitUrl('https://github.com/adobe/helix-shared.git#main');
// Get the raw content URL
console.log(url.raw);
// 'https://raw.githubusercontent.com/adobe/helix-shared/main'
// Get the raw content root URL
console.log(url.rawRoot);
// 'https://raw.githubusercontent.com'
// Get the API root URL
console.log(url.apiRoot);
// 'https://api.github.com'
`
You can provide default values that will be used if the URL doesn't specify certain properties:
`js
const url = new GitUrl('https://github.com/adobe/helix-shared.git', {
ref: 'main',
path: '/src'
});
console.log(url.ref); // 'main'
console.log(url.path); // '/src'
`
Convert GitUrl objects to and from JSON:
`js
const url = new GitUrl('https://github.com/adobe/helix-shared.git#main');
// Convert to JSON
const json = url.toJSON();
console.log(json);
// {
// protocol: 'https',
// host: 'github.com',
// hostname: 'github.com',
// port: '',
// owner: 'adobe',
// repo: 'helix-shared',
// ref: 'main',
// path: ''
// }
// Create from JSON
const urlFromJson = new GitUrl(json);
console.log(urlFromJson.toString());
// 'https://github.com/adobe/helix-shared.git#main'
`
For more compact serialization, use the minimal option:
`js
const url = new GitUrl({
owner: 'adobe',
repo: 'helix-shared',
ref: 'main'
});
console.log(url.toJSON({ minimal: true }));
// { owner: 'adobe', repo: 'helix-shared', ref: 'main' }
`
Compare two Git URLs while ignoring transport-level differences:
`js
const url1 = new GitUrl('https://github.com/adobe/helix-shared.git#main');
const url2 = new GitUrl('ssh://git@github.com/adobe/helix-shared.git#main');
console.log(url1.equalsIgnoreTransport(url2)); // true
`
The GitUrl class has special handling for local repositories (specific to Helix):
`js
const localUrl = new GitUrl('https://localhost/local/default.git');
console.log(localUrl.isLocal); // true
`
- protocol - Transport protocol (e.g., 'https', 'ssh')hostname
- - Repository provider hostname (e.g., 'github.com')host
- - Repository provider host with port (e.g., 'github.com:443')port
- - Repository provider portowner
- - Repository ownerrepo
- - Repository name (without .git extension)ref
- - Repository reference, such as a branch or tagpath
- - Resource path within the repositoryraw
- - Raw content URL for the repositoryrawRoot
- - Root URL for raw contentapiRoot
- - Root URL for the APIisLocal
- - Whether this is a local Helix repository
- toString() - Returns the string representation of the Git URLtoJSON(options)
- - Returns a plain object representation. Options:minimal
- : Returns only non-default propertieskeepFormat
- : Preserves the original format (string vs object)toYAMLNode(doc, forceObject)
- - Returns a YAML node representationequalsIgnoreTransport(other)
- - Compares URLs ignoring protocol and authentication
The expected Git URL format is:
``
For SCP-style URLs:
``
git@
- owner - The repository owner or organizationrepo
- - The repository name
- protocol - Defaults to 'https'hostname
- - Defaults to 'github.com'port
- - Defaults to standard port for the protocolpath
- - Resource path within the repositoryref
- - Branch, tag, or commit reference. Defaults to 'master' in raw URLs
For GitHub URLs, the raw property automatically uses raw.githubusercontent.com instead of raw.github.com.
When the hostname is an IP address, the raw and API URLs are constructed differently:
`js
const url = new GitUrl('http://127.0.0.1:8080/company/repo.git');
console.log(url.raw);
// 'http://127.0.0.1:8080/raw/company/repo/master'
`
URLs with SSH protocol automatically convert to HTTPS for raw and API URLs:
`js
const url = new GitUrl('ssh://git@github.com/adobe/helix-shared.git');
console.log(url.raw);
// 'https://raw.githubusercontent.com/adobe/helix-shared/master'
``