repo-utils
Utils for normalizing and formatting repo data.
You might also be interested in parse-git-config.
Install
Install with npm:
$ npm install --save repo-utils
Usage
var repo = require('repo-utils');
API
Get the name
for a repository from: - github repository path (owner/project-name
) - github URL - absolute file path to a directory on the local file system (.
and ''
may be used as aliases for the current working directory)
Example
repo.name(process.cwd());
repo.name('.');
repo.name();
repo.name('https://github.com/jonschlinkert/repo-utils');
repo.name('jonschlinkert/repo-utils');
Params
cwd
{String}: Absolute file path or github URLreturns
{String}: Project name
Create a github repository string in the form of owner/name
, from: - full github repository URL - object returned from url.parse
- list of arguments in the form of owner, name
Example
repo.repository('jonschlinkert', 'micromatch');
repo.repository({owner: 'jonschlinkert', repository: 'micromatch'});
repo.repository('https://github.com/jonschlinkert/micromatch');
Params
owner
{String}: Repository ownername
{String}: Repository namereturns
{String}: Reps
Create a homepage
URL from a github repository path or github repository URL.
Example
repo.homepage('jonschlinkert/repo-utils');
Params
repository
{String}: Repository in the form of owner/project-name
options
{Object}returns
{String}: Formatted github homepage url.
Create a GitHub issues
URL.
Example
repo.isses('jonschlinkert/micromatch');
Params
repository
{String}: Repository in the form of owner/project-name
or full github project URL.options
{Object}returns
{String}
Create a GitHub bugs
URL. Alias for .issues.
Example
repo.bugs('jonschlinkert/micromatch');
Params
repository
{String}: Repository in the form of owner/project-name
options
{Object}returns
{String}
Create a github https
URL.
Example
repo.https('jonschlinkert/micromatch');
Params
repository
{String}: Repository in the form of owner/project-name
options
{Object|String}: Options object or optional branchbranch
{String}: Optionally specify a branchreturns
{String}
Create a travis URL.
Example
repo.travis('jonschlinkert/micromatch');
Params
repository
{String}: Repository in the form of owner/project-name
options
{Object|String}: Options object or optional branchbranch
{String}: Optionally specify a branchreturns
{String}
Create a URL for a file in a github repository.
Example
repo.file('https://github.com/jonschlinkert/micromatch', 'README.md');
repo.raw('jonschlinkert/micromatch', 'README.md');
Params
repository
{String}: Repository in the form of owner/project-name
or full GitHub repository URL.branch
{String}: Optionally specify a branchpath
{String}: Path to the file, relative to the repository root.returns
{String}
Create a github "raw" content URL.
Example
repo.raw('https://github.com/jonschlinkert/micromatch', 'README.md');
repo.raw('jonschlinkert/micromatch', 'README.md');
Params
repository
{String}: Repository in the form of owner/project-name
options
{Object|String}: Options object or optional branchbranch
{String}: Optionally specify a branchreturns
{String}
Return true if the given string looks like a github URL.
Example
utils.isGithubUrl('https://github.com/whatever');
utils.isGithubUrl('https://foo.com/whatever');
Params
str
{String}: URL to testreturns
{Boolean}
Parse a GitHub repository URL or repository owner/project-name
into an object.
Example
repo.parse('https://raw.githubusercontent.com/jonschlinkert/micromatch/master/README.md');
{ protocol: 'https:',
slashes: true,
hostname: 'raw.githubusercontent.com',
host: 'raw.githubusercontent.com',
pathname: 'https://raw.githubusercontent.com/foo/bar/master/README.md',
path: '/foo/bar/master/README.md',
href: 'https://raw.githubusercontent.com/foo/bar/master/README.md',
owner: 'foo',
name: 'bar',
repo: 'foo/bar',
repository: 'foo/bar',
branch: 'master' }
Params
repositoryURL
{String}: Full repository URL, or repository path in the form of owner/project-name
options
{Object}returns
{Boolean}
Parse a GitHub repository
path or URL by calling repo.parseUrl()
, then expands it into an object of URLs. (the object also includes properties returned from .parse()
). A file path maybe be passed as the second argument to include raw
and file
properties in the result.
Example
repo.expand('https://github.com/abc/xyz.git', 'README.md');
{ protocol: 'https:',
slashes: true,
hostname: 'github.com',
host: 'github.com',
pathname: 'https://github.com/abc/xyz.git',
path: '/abc/xyz.git',
href: 'https://github.com/abc/xyz.git',
owner: 'abc',
name: 'xyz',
repo: 'abc/xyz',
repository: 'abc/xyz',
branch: 'master',
host_api: 'api.github.com',
host_raw: 'https://raw.githubusercontent.com',
api: 'https://api.github.com/repos/abc/xyz',
tarball: 'https://api.github.com/repos/abc/xyz/tarball/master',
clone: 'https://github.com/abc/xyz',
zip: 'https://github.com/abc/xyz/archive/master.zip',
https: 'https://github.com/abc/xyz',
travis: 'https://travis-ci.org/abc/xyz',
file: 'https://github.com/abc/xyz/blob/master/README.md',
raw: 'https://raw.githubusercontent.com/abc/xyz/master/README.md' }
Params
repository
{String}file
{String}: Optionally pass a repository file path.returns
{String}
Get the local git config path, or global if a local .git
repository does not exist.
Example
console.log(repo.gitConfigPath());
console.log(repo.gitConfigPath());
/Users/jonschlinkert/.gitconfig
console.log(repo.gitConfigPath('global'));
/Users/jonschlinkert/.gitconfig
Params
type
{String}: Pass global
to get the global git config path regardless of whether or not a local repository exists.returns
{String}: Returns the local or global git path
Get and parse global git config.
Example
console.log(repo.gitConfig());
Params
options
{Object}: To get a local .git
config, pass {type: 'local'}
returns
{Object}
Get an owner string from the given object or string.
Example
console.log(repo.owner(require('./package.json')));
Params
config
{String|Object}: If an object is passed, it must have a repository
, url
or author
propert (looked for in that order), otherwise if a string is passed it must be parse-able by the parseUrl method.returns
{String}
Normalize a "person" object. If a "person" string is passed (like author
, contributor
etc) it is parsed into an object, otherwise the object is returned.
Example
console.log(repo.person('Brian Woodward (https://github.com/doowb)'));
console.log(repo.person({ name: 'Brian Woodward', url: 'https://github.com/doowb' }));
Params
val
{String|Object}returns
{Object}
Returns an author
object from the given given config object. If config.author
is a string it will be parsed into an object.
Example
console.log(repo.author({
author: 'Brian Woodward (https://github.com/doowb)'
}));
console.log(repo.author({
name: 'Brian Woodward',
url: 'https://github.com/doowb'
}));
Params
config
{Object}: Object with an author
propertyreturns
{Object}
Returns the author.name
from the given config object. If config.author
is a string it will be parsed into an object first.
Example
console.log(repo.authorName({
author: 'Brian Woodward (https://github.com/doowb)'
}));
console.log(repo.authorName({
name: 'Brian Woodward',
url: 'https://github.com/doowb'
}));
Params
config
{Object}: Object with an author
propertyreturns
{Object}
Returns the author.url
from the given config object. If config.author
is a string it will be parsed into an object first.
Example
console.log(repo.authorUrl({
author: 'Brian Woodward (https://github.com/doowb)'
}));
console.log(repo.authorUrl({
name: 'Brian Woodward',
url: 'https://github.com/doowb'
}));
Params
config
{Object}: Object with an author
propertyreturns
{Object}
Returns the author.email
from the given config object. If config.author
is a string it will be parsed into an object first.
Example
console.log(repo.authorEmail({
author: 'Brian Woodward <brian.woodward@sellside.com> (https://github.com/doowb)'
}));
console.log(repo.authorEmail({
name: 'Brian Woodward',
url: 'https://github.com/doowb',
email: 'brian.woodward@sellside.com'
}));
Params
config
{Object}: Object with an author
propertyreturns
{Object}
Returns the author.username
from the given config object. If config.author
is a string it will be parsed into an object first.
Example
console.log(repo.authorUsername({
author: 'Brian Woodward <brian.woodward@sellside.com> (https://github.com/doowb)'
}));
console.log(repo.authorUsername({
name: 'Brian Woodward',
url: 'https://github.com/doowb',
email: 'brian.woodward@sellside.com'
}));
Params
config
{Object}: Object with an author
propertyreturns
{Object}
Returns a username
from the given config object, by first attempting to get author.username
, then
Example
console.log(repo.username({
author: 'Brian Woodward <brian.woodward@sellside.com> (https://github.com/doowb)'
}));
console.log(repo.username({
name: 'Brian Woodward',
url: 'https://github.com/doowb',
email: 'brian.woodward@sellside.com'
}));
Params
config
{Object}: Object with an author
propertyreturns
{Object}
Coverage
As of October 12, 2016:
Statements : 71.19% ( 126/177 )
Branches : 59.13% ( 68/115 )
Functions : 59.09% ( 13/22 )
Lines : 71.59% ( 126/176 )
About
Related projects
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Contributors
Building docs
(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)
To generate the readme and API documentation with verb:
$ npm install -g verb verb-generate-readme && verb
Running tests
Install dev dependencies:
$ npm install -d && npm test
Author
Jon Schlinkert
License
Copyright © 2016, Jon Schlinkert.
Released under the MIT license.
This file was generated by verb-generate-readme, v0.1.31, on October 12, 2016.