repo-utils

repo-utils

Utils for normalizing and formatting repo data.

You might also be interested in parse-git-config.

Install

Install with npm:

$ npm install repo-utils --save

Usage

var repo = require('repo-utils');

API

.name

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)

Params

• cwd {String}: Absolute file path or github URL
• returns {String}: Project name

Example

repo.name(process.cwd());
//=> 'repo-utils'
repo.name('.');
//=> 'repo-utils'
repo.name();
//=> 'repo-utils'

repo.name('https://github.com/jonschlinkert/repo-utils');
//=> 'repo-utils'
repo.name('jonschlinkert/repo-utils');
//=> 'repo-utils'

.repository

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

Params

• owner {String}: Repository owner
• name {String}: Repository name
• returns {String}: Reps

Example

repo.repository('jonschlinkert', 'micromatch');
//=> 'jonschlinkert/micromatch'

repo.repository({owner: 'jonschlinkert', repository: 'micromatch'});
//=> 'jonschlinkert/micromatch'

repo.repository('https://github.com/jonschlinkert/micromatch');
//=> 'jonschlinkert/micromatch'

.homepage

Create a homepage URL from a github repository path or github repository URL.

Params

• repository {String}: Repository in the form of owner/project-name
• options {Object}
• returns {String}: Formatted github homepage url.

Example

repo.homepage('jonschlinkert/repo-utils');
//=> 'https://github.com/jonchlinkert/repo-utils'

.issues

Create a GitHub issues URL.

Params

• repository {String}: Repository in the form of owner/project-name or full github project URL.
• options {Object}
• returns {String}

Example

repo.isses('jonschlinkert/micromatch');
//=> 'https://github.com/jonchlinkert/micromatch/issues'

.bugs

Create a GitHub bugs URL. Alias for .issues.

Params

• repository {String}: Repository in the form of owner/project-name
• options {Object}
• returns {String}

Example

repo.bugs('jonschlinkert/micromatch');
//=> 'https://github.com/jonchlinkert/micromatch/issues'

.https

Create a github https URL.

Params

• repository {String}: Repository in the form of owner/project-name
• options {Object|String}: Options object or optional branch
• branch {String}: Optionally specify a branch
• returns {String}

Example

repo.https('jonschlinkert/micromatch');
//=> 'https://github.com/jonchlinkert/micromatch'

.travis

Create a travis URL.

Params

• repository {String}: Repository in the form of owner/project-name
• options {Object|String}: Options object or optional branch
• branch {String}: Optionally specify a branch
• returns {String}

Example

repo.travis('jonschlinkert/micromatch');
//=> 'https://travis-ci.org/jonschlinkert/micromatch'

.file

Create a URL for a file in a github repository.

Params

• repository {String}: Repository in the form of owner/project-name or full GitHub repository URL.
• branch {String}: Optionally specify a branch
• path {String}: Path to the file, relative to the repository root.
• returns {String}

Example

repo.file('https://github.com/jonschlinkert/micromatch', 'README.md');
//=> 'https://raw.githubusercontent.com/jonschlinkert/micromatch/master/README.md'

repo.raw('jonschlinkert/micromatch', 'README.md');
//=> 'https://raw.githubusercontent.com/jonschlinkert/micromatch/master/README.md'

.raw

Create a github "raw" content URL.

Params

• repository {String}: Repository in the form of owner/project-name
• options {Object|String}: Options object or optional branch
• branch {String}: Optionally specify a branch
• returns {String}

Example

repo.raw('https://github.com/jonschlinkert/micromatch', 'README.md');
//=> 'https://raw.githubusercontent.com/jonschlinkert/micromatch/master/README.md'

repo.raw('jonschlinkert/micromatch', 'README.md');
//=> 'https://raw.githubusercontent.com/jonschlinkert/micromatch/master/README.md'

.isGithubUrl

Return true if the given string looks like a github URL.

Params

• str {String}: URL to test
• returns {Boolean}

Example

utils.isGithubUrl('https://github.com/whatever');
//=> true
utils.isGithubUrl('https://foo.com/whatever');
//=> false

.parseUrl

Parse a GitHub repository URL or repository owner/project-name into an object.

Params

• repositoryURL {String}: Full repository URL, or repository path in the form of owner/project-name
• options {Object}
• returns {Boolean}

Example

// see the tests for supported formats
repo.parse('https://raw.githubusercontent.com/jonschlinkert/micromatch/master/README.md');

// results in:
{ 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' }

.expandUrl

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.

Params

• repository {String}
• file {String}: Optionally pass a repository file path.
• returns {String}

Example

// see the tests for supported formats
repo.expand('https://github.com/abc/xyz.git', 'README.md');

// results in:
{ 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' }

.gitConfigPath

Get the local git config path, or global if a local .git repository does not exist.

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

Example

console.log(repo.gitConfigPath());
//=> /Users/jonschlinkert/dev/repo-utils/.git/config

// if local .git repo does not exist
console.log(repo.gitConfigPath());
/Users/jonschlinkert/.gitconfig

// get global path
console.log(repo.gitConfigPath('global'));
/Users/jonschlinkert/.gitconfig

.gitConfig

Get and parse global git config.

Params

• options {Object}: To get a local .git config, pass {type: 'local'}
• returns {Object}

Example

console.log(repo.gitConfig());

.owner

Get an owner string from the given object or string.

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}

Example

console.log(repo.owner(require('./package.json')));
//=> 'jonschlinkert'

.person

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.

Params

• val {String|Object}
• returns {Object}

Example

console.log(repo.person('Brian Woodward (https://github.com/doowb)'));
//=> { name: 'Brian Woodward', url: 'https://github.com/doowb' }
console.log(repo.person({ name: 'Brian Woodward', url: 'https://github.com/doowb' }));
//=> { name: 'Brian Woodward', url: 'https://github.com/doowb' }

.author

Returns an author object from the given given config object. If config.author is a string it will be parsed into an object.

Params

• config {Object}: Object with an author property
• returns {Object}

Example

console.log(repo.author({
  author: 'Brian Woodward (https://github.com/doowb)'
}));
//=> { name: 'Brian Woodward', url: 'https://github.com/doowb' }

console.log(repo.author({
  name: 'Brian Woodward',
  url: 'https://github.com/doowb'
}));
//=> { name: 'Brian Woodward', url: 'https://github.com/doowb' }

.authorName

Returns the author.name from the given config object. If config.author is a string it will be parsed into an object first.

Params

• config {Object}: Object with an author property
• returns {Object}

Example

console.log(repo.authorName({
  author: 'Brian Woodward (https://github.com/doowb)'
}));
//=> 'Brian Woodward'

console.log(repo.authorName({
  name: 'Brian Woodward',
  url: 'https://github.com/doowb'
}));
//=> 'Brian Woodward'

.authorUrl

Returns the author.url from the given config object. If config.author is a string it will be parsed into an object first.

Params

• config {Object}: Object with an author property
• returns {Object}

Example

console.log(repo.authorUrl({
  author: 'Brian Woodward (https://github.com/doowb)'
}));
//=> 'https://github.com/doowb'

console.log(repo.authorUrl({
  name: 'Brian Woodward',
  url: 'https://github.com/doowb'
}));
//=> 'https://github.com/doowb'

.authorEmail

Returns the author.email from the given config object. If config.author is a string it will be parsed into an object first.

Params

• config {Object}: Object with an author property
• returns {Object}

Example

console.log(repo.authorEmail({
author: 'Brian Woodward <[e-mail]> (https://github.com/doowb)'
}));
//=> '[e-mail]'

console.log(repo.authorEmail({
  name: 'Brian Woodward',
  url: 'https://github.com/doowb',
email: '[e-mail]'
}));
//=> '[e-mail]'

.authorUsername

Returns the author.username from the given config object. If config.author is a string it will be parsed into an object first.

Params

• config {Object}: Object with an author property
• returns {Object}

Example

console.log(repo.authorUsername({
author: 'Brian Woodward <[e-mail]> (https://github.com/doowb)'
}));
//=> 'doowb'

console.log(repo.authorUsername({
  name: 'Brian Woodward',
  url: 'https://github.com/doowb',
email: '[e-mail]'
}));
//=> 'doowb'

.username

Returns a username from the given config object, by first attempting to get author.username, then

Params

• config {Object}: Object with an author property
• returns {Object}

Example

console.log(repo.username({
author: 'Brian Woodward <[e-mail]> (https://github.com/doowb)'
}));
//=> 'doowb'

console.log(repo.username({
  name: 'Brian Woodward',
  url: 'https://github.com/doowb',
email: '[e-mail]'
}));
//=> 'doowb'

Coverage

As of May 03, 2016:

Statements   : 71.19% ( 126/177 )
Branches     : 59.13% ( 68/115 )
Functions    : 59.09% ( 13/22 )
Lines        : 71.59% ( 126/176 )

Related projects

You might also be interested in these projects:

• git-config-path: Resolve the path to the user's global .gitconfig. | homepage
• parse-author: Parse a string into an object with name, email and url properties following npm conventions.… more | homepage
• parse-git-config: Parse .git/config into a JavaScript object. sync or async. | homepage
• project-name: Get the name of a project, from package.json, git config, or basename of the current… more | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Building docs

Generate readme and API documentation with verb:

$ npm install verb && npm run docs

Or, if verb is installed globally:

$ verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2016, Jon Schlinkert. Released under the MIT license.

---

This file was generated by verb, v0.9.0, on May 03, 2016.