Neurosis Prevention Mechanism

    repo-utils

    0.4.1 • Public • Published

    repo-utils NPM version NPM monthly downloads NPM total downloads Linux Build Status

    Utils for normalizing and formatting repo data.

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

    Table of Contents - [Install](#install) - [Usage](#usage) - [API](#api) - [Coverage](#coverage) - [About](#about)

    Install

    Install with npm:

    $ npm install --save repo-utils

    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 <brian.woodward@sellside.com> (https://github.com/doowb)'
    }));
    //=> 'brian.woodward@sellside.com'
     
    console.log(repo.authorEmail({
      name: 'Brian Woodward',
      url: 'https://github.com/doowb',
    email: 'brian.woodward@sellside.com'
    }));
    //=> 'brian.woodward@sellside.com'

    .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 <brian.woodward@sellside.com> (https://github.com/doowb)'
    }));
    //=> 'doowb'
     
    console.log(repo.authorUsername({
      name: 'Brian Woodward',
      url: 'https://github.com/doowb',
    email: 'brian.woodward@sellside.com'
    }));
    //=> '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 <brian.woodward@sellside.com> (https://github.com/doowb)'
    }));
    //=> 'doowb'
     
    console.log(repo.username({
      name: 'Brian Woodward',
      url: 'https://github.com/doowb',
    email: 'brian.woodward@sellside.com'
    }));
    //=> 'doowb'

    Coverage

    As of January 30, 2017:

    Statements   : 88.99% ( 202/227 )
    Branches     : 79.69% ( 102/128 )
    Functions    : 73.33% ( 22/30 )
    Lines        : 88.99% ( 202/227 )
    

    About

    Related projects

    Contributing

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

    Contributors

    Commits Contributor
    35 jonschlinkert
    6 doowb
    1 tunnckoCore

    Building docs

    (This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

    To generate the readme, run the following command:

    $ npm install -g verbose/verb#dev verb-generate-readme && verb

    Running tests

    Install dev dependencies:

    $ npm install && npm test

    Author

    Jon Schlinkert

    License

    Copyright © 2017, Jon Schlinkert. MIT


    This file was generated by verb-generate-readme, v0.4.2, on January 30, 2017.

    Install

    npm i repo-utils

    DownloadsWeekly Downloads

    22,534

    Version

    0.4.1

    License

    MIT

    Last publish

    Collaborators

    • doowb
    • jonschlinkert