find-githost
v1.0.0
Published
Get repository info from a directory, package.json, url, npm shorthand or git remote
Downloads
1,322
Maintainers
Readme
find-githost
Get repository info from a directory, package.json
, url, npm shorthand or git remote. Backed by the same URL parser as npm. Supports GitHub, GitLab and BitBucket.
Table of Contents
- Usage
- API
- Factories
- Properties
- Methods
githost.shortcut([options])
githost.slug([options])
githost.https([options])
githost.ssh([options])
githost.sshurl([options])
githost.git([options])
githost.homepage()
githost.bugs()
githost.browse([path][, fragment][, options])
githost.file(path[, options])
githost.tarball([options])
githost.toString([options])
- Install
- License
Usage
Get info from package.json
or git remote origin, whichever is found first:
const Githost = require('find-githost')
const githost = Githost.fromDir('.')
console.log(githost.type) // github
console.log(githost.owner) // vweevers
console.log(githost.name) // find-githost
console.log(githost.ssh()) // [email protected]:vweevers/find-githost.git
console.log(githost.https()) // https://github.com/vweevers/find-githost.git
console.log(githost.homepage()) // https://github.com/vweevers/find-githost
Get info from URL or npm shorthands:
const githost = Githost.fromUrl('vweevers/find-githost#d6aeb7c')
console.log(githost.toString())
console.log(githost.browse('README.md'))
console.log(githost.browse('CHANGELOG.md', { committish: 'v1.0.0' }))
vweevers/find-githost#d6aeb7c
https://github.com/vweevers/find-githost/tree/d6aeb7c/README.md
https://github.com/vweevers/find-githost/tree/v1.0.0/CHANGELOG.md
API
Factories
githost = Githost.fromUrl(url[, options])
Get info from a URL or npm shortcut. Recognizes Git, SSH and HTTPS urls, as well as shortcuts (github:vweevers/find-githost
) and for GitHub specifically, the shorter form vweevers/find-githost
. Options:
committish
(string or boolean): if a string, override the committish of input. Iffalse
, strip committish.defaultBranch
(string, defaultmain
): branch name to use for files and tarballs when committish is not presentoptional
(boolean, default false): if no valid URL is found, returnnull
instead of throwing an error.
The committish
and defaultBranch
options can also be set per method. See the documentation of methods below, which should also clarify when these options apply.
githost = Githost.fromDir(cwd[, options])
Get info from package.json
or git remote origin in the cwd
directory, whichever is found first. Options:
roam
(boolean, default false): look in parent directories too- Other options are passed on to
fromUrl()
.
githost = Githost.fromPkg(cwd[, options])
Get info from the repository
field of a package.json
in the cwd
directory. Options:
roam
(boolean, default false): look in parent directories too- Other options are passed on to
fromUrl()
.
githost = Githost.fromPkg(pkg[, options])
Get info from the repository
field of a parsed package.json
object. Options are passed on to fromUrl()
.
githost = Githost.fromGit(cwd[, options])
Get info from git remote origin (taken from local git config). Options:
roam
(boolean, default false): look in parent directories too- Other options are passed on to
fromUrl()
.
Properties
githost.type
String, one of github
, gist
, gitlab
or bitbucket
.
githost.owner
String, repository owner.
githost.name
String, repository name.
githost.committish
String if committish is present, else null
.
githost.format
String, original format of input URL, one of shortcut
, slug
, https
, ssh
, sshurl
or git
.
githost.raw
String, original input URL.
githost.hostname
String, domain of remote, e.g. github.com
for type github
.
Methods
githost.shortcut([options])
Returns an npm-style shortcut in the form of type:owner/name(#committish)
. Options:
committish
(string or boolean): if a string, override committish. Iffalse
, strip committish.
githost.slug([options])
Returns an npm-style shortcut for GitHub repositories in the form of owner/name(#committish)
. Options:
committish
(string or boolean): if a string, override committish. Iffalse
, strip committish.
githost.https([options])
Returns Git URL for HTTPS protocol in the form of https://hostname/owner/name.git(#committish)
, for example https://github.com/vweevers/find-githost.git
. Options:
committish
(string or boolean): if a string, override committish. Iffalse
, strip committish.
githost.ssh([options])
Returns Git URL for SSH protocol in the short form of git@hostname:owner/name.git(#committish)
, for example [email protected]:vweevers/find-githost.git
. Options:
committish
(string or boolean): if a string, override committish. Iffalse
, strip committish.
githost.sshurl([options])
Returns Git URL for SSH protocol in the long form of ssh://git@hostname/owner/name.git(#committish)
, for example ssh://[email protected]/vweevers/find-githost.git
. Options:
committish
(string or boolean): if a string, override committish. Iffalse
, strip committish.
githost.git([options])
Returns Git URL for Git protocol in the form of git://hostname/owner/name.git(#committish)
, for example git://github.com/vweevers/find-githost.git
. Options:
committish
(string or boolean): if a string, override committish. Iffalse
, strip committish.
githost.homepage()
Returns HTTP(S) URL of homepage, for example https://github.com/vweevers/find-githost
.
githost.bugs()
Returns HTTP(S) URL of issue tracker, for example https://github.com/vweevers/find-githost/issues
.
githost.browse([path][, fragment][, options])
Returns HTTP(S) URL for browsing a file or directory. For example https://github.com/vweevers/find-githost/tree/main/README.md#usage
given path README.md
and fragment #usage
. For the top-most directory, omit the path
argument or use /
. Options:
committish
(string or boolean): if a string, override committish. Iffalse
, use default branch.defaultBranch
(string, defaultmain
): branch name to use when committish is not present.
githost.file(path[, options])
Returns HTTP(S) URL for the raw contents of path
, for example https://raw.githubusercontent.com/vweevers/find-githost/main/index.js
given path index.js
. Options:
committish
(string or boolean): if a string, override committish. Iffalse
, use default branch.defaultBranch
(string, defaultmain
): branch name to use when committish is not present.
githost.tarball([options])
Returns HTTP(S) tarball URL, for example https://codeload.github.com/vweevers/find-githost/tar.gz/v1.0.0
given committish v1.0.0
. Options:
committish
(string or boolean): if a string, override committish. Iffalse
, use default branch.defaultBranch
(string, defaultmain
): branch name to use when committish is not present.
githost.toString([options])
Returns a string representation. Options:
format
(string, defaults to format of input): one ofshortcut
,slug
,https
,ssh
,sshurl
,git
.committish
(string or boolean): if a string, override committish. Iffalse
, strip committish.
Install
With npm do:
npm install find-githost
License
MIT © Vincent Weevers