grunt-repos/README.md

Grunt task to download a list of repos from GitHub's API

# grunt-repos [![NPM version](https://badge.fury.io/js/grunt-repos.png)](http://badge.fury.io/js/grunt-repos) 

> Grunt task to download a list of repos from GitHub's API

## Getting Started
_If you haven't used [grunt][] before, be sure to check out the [Getting Started][] guide._

From the same directory as your project's [Gruntfile][Getting Started] and [package.json][], install this plugin with the following command:

```bash
npm install grunt-repos --save-dev
```

Once that's done, add this line to your project's Gruntfile:

```js
grunt.loadNpmTasks('grunt-repos');
```

If the plugin has been installed correctly, running `grunt --help` at the command line should list the newly-installed plugin's task or tasks. In addition, the plugin should be listed in package.json as a `devDependency`, which ensures that it will be installed whenever the `npm install` command is run.



## The "repos" task

### Overview
In your project's Gruntfile, add a section named `repos` to the data object passed into `grunt.initConfig()`.

```js
grunt.initConfig({
  repos: {
    options: {
      // Task-specific options go here.
    },
    target: {
      // Target-specific file lists and/or options go here.
    }
  }
})
```


### Options
#### username
Type: `String`
Default: `assemble`

List repositories for the specified org. Using `src`, you must also pass an HTTP query string as a parameter, e.g. `repos?page=1&per_page=100`. This is done the way to keep the task light and flexible. (See the [Gruntfile](./Gruntfile.js) for examples).

#### path
Type: `String`
Default: `/orgs/assemble/`

If you don't like how the task constructs the path by default, a custom path may be defined. Any custom parameters may be specified as segments in the path or passed as an HTTP query string parameter in the `src`.

#### filterBy
Type: `String`
Default: `name`

The property to use to filter the collection. This option works in conjunction with `options.include` and `options.exclude`.

#### exclude
Type: `String|Array`
Default: `undefined`

Keywords to use for excluding repos from the returned array. If the property defined using `filterBy` contains any values with excluded keywords, the repo will be omitted from the list.

#### include
Type: `String|Array`
Default: `undefined`

Keywords to use for whitelisting repos in the returned array. Unless excluded, if the property defined using `filterBy` contains any values with these keywords, the repo will be included in the list.

#### sortBy
Type: `String`
Default: `name`

The property by which to sort the collection.

#### sortOrder
Type: `String`
Default: `asc`

The order in which to sort the collection.

#### namespace
Type: `String`
Default: `"repos": []`

Add the list of repos to an array with the given property name. If left undefined, `"repos": []` will be used. Specify `false` if you don't want to add the array to a property.


### Usage Examples
### namespaced list
Add the list of repos to an array with the given property name.

```js
grunt.initConfig({
  repos: {
    options: {
      path: '/orgs/assemble/',
      namespace: 'assemble'
    },
    files: {
      'test/fixtures/data/helpers.json': ['repos?page=1&per_page=100']
    }
  }
});
```
Returns:

```json
{
  "assemble": [
    {
      "id": 5916767,
      "name": "assemble",
      "full_name": "assemble/assemble",
      "owner": {
        "login": "assemble",
        "id": 2645080,
        ...
      }
    }
  ]
}
```

### no namespace

Or just return the array of repos.

```js
grunt.initConfig({
  repos: {
    no_namespace: {
      options: {
        path: '/orgs/assemble/',
        namespace: false,
      },
      files: {
        'test/actual/no_namespace.json': ['repos?page=1&per_page=100']
      }
    }
  }
});
```

Returns:

```json
[
  {
    "id": 5916767,
    "name": "assemble",
    "full_name": "assemble/assemble",
    "owner": {
      "login": "assemble",
      "id": 2645080,
      ...
    }
  }
]
```


## Contributing
Find a bug? Have a feature request? Please [create an Issue](https://github.com/assemble/grunt-repos/issues). Pull requests are also encouraged.
If you find this project useful, please consider "starring" it to show your support! Thanks!


## Authors

**Jon Schlinkert**

+ [github/jonschlinkert](https://github.com/jonschlinkert)
+ [twitter/jonschlinkert](http://twitter.com/jonschlinkert)

**Brian Woodward**

+ [github/doowb](https://github.com/doowb)
+ [twitter/doowb](http://twitter.com/jonschlinkert)


## License
Copyright (c) 2013 Jon Schlinkert, contributors.
Released under the MIT license

***

_This file was generated by [grunt-readme](https://github.com/assemble/grunt-readme) on Thursday, November 28, 2013._

[grunt]: http://gruntjs.com/
[Getting Started]: https://github.com/gruntjs/grunt/blob/devel/docs/getting_started.md
[package.json]: https://npmjs.org/doc/json.html