<commit_before># Octokit

Ruby toolkit for the GitHub API.

![Logo][logo]
[logo]: http://cl.ly/image/3Y013H0A2z3z/gundam-ruby.png

Octokit 2.0 is out, check the [Upgrade Guide](#upgrading-guide) before
upgrading from 1.x.

## Philosophy

API wrappers [should reflect the idioms of the language in which they were
written][wrappers]. Octokit.rb wraps the [GitHub API][github-api] in a flat API
client that follows Ruby conventions and requires little knowledge of REST.
Most methods have positional arguments for required input and an options hash
for optional parameters, headers, or other options:

```ruby
# Fetch a README with Accept header for HTML format
Octokit.readme 'al3x/sovereign', :accept => 'application/vnd.github.html'
```


[wrappers]: http://wynnnetherland.com/journal/what-makes-a-good-api-wrapper
[github-api]: http://developer.github.com

## Quick start

Install via Rubygems

    gem install octokit

... or add to your Gemfile

    gem "octokit", "~> 3.0"

### Making requests

API methods are available as module methods (consuming module-level
configuration) or as client instance methods.

```ruby
# Provide authentication credentials
Octokit.configure do |c|
  c.login = 'defunkt'
  c.password = '<PASSWORD>!'
end

# Fetch the current user
Octokit.user
```
or

```ruby
# Provide authentication credentials
client = Octokit::Client.new(:login => 'defunkt', :password => '<PASSWORD>!')
# Fetch the current user
client.user
```

### Consuming resources

Most methods return a `Resource` object which provides dot notation and `[]`
access for fields returned in the API response.

```ruby
# Fetch a user
user = Octokit.user 'jbarnette'
puts user.name
# => "<NAME>"
puts user.fields
# => <Set: {:login, :id, :gravatar_id, :type, :name, :company, :blog, :location, :email, :hireable, :bio, :public_repos, :followers, :following, :created_at, :updated_at, :public_gists}>
puts user[:company]
# => "GitHub"
user.rels[:gists].href
# => "https://api.github.com/users/jbarnette/gists"
```

**Note:** URL fields are culled into a separate `.rels` collection for easier
[Hypermedia](#hypermedia-agent) support.

### Accessing HTTP responses

While most methods return a `Resource` object or a Boolean, sometimes you may
need access to the raw HTTP response headers. You can access the last HTTP
response with `Client#last_response`:

```ruby
user      = Octokit.user 'andrewpthorp'
response  = Octokit.last_response
etag      = response.headers[:etag]
```

## Authentication

Octokit supports the various [authentication methods supported by the GitHub
API][auth]:

### Basic Authentication

Using your GitHub username and password is the easiest way to get started
making authenticated requests:

```ruby
client = Octokit::Client.new \
  :login    => 'defunkt',
  :password => '<PASSWORD>!'

user = client.user
user.login
# => "defunkt"
```
While Basic Authentication makes it easy to get started quickly, OAuth access
tokens are the preferred way to authenticate on behalf of users.

### OAuth access tokens

[OAuth access tokens][oauth] provide two main benefits over using your username
and password:

* **Revokable access**. Access tokens can be revoked, removing access for just
  that token without having to change your password everywhere.
* **Limited access**. Access tokens have [access scopes][] which allow for more
  granular access to API resources. For instance, you can grant a third party
  access to your gists but not your private repositories.

To use an access token with the Octokit client, just pass it in lieu of your
username and password:

```ruby
client = Octokit::Client.new(:access_token => "<your 40 char token>")

user = client.user
user.login
# => "defunkt"
```

You can use `.create_authorization` to create a token using Basic Authorization
that you can use for subsequent calls.

### Two-Factor Authentication

[Two-Factor Authentication](https://help.github.com/articles/about-two-factor-authentication) brings added security to the account by requiring more information to login.

Using two-factor authentication for API calls is as simple as adding the [required header](http://developer.github.com/v3/auth/#working-with-two-factor-authentication) as an option:

```ruby
client = Octokit::Client.new \
  :login    => 'defunkt',
  :password => '<PASSWORD>!'<commit_msg>Add link to create access token article & example of create_authorization. [ci skip]<commit_after># Octokit

Ruby toolkit for the GitHub API.

![Logo][logo]
[logo]: http://cl.ly/image/3Y013H0A2z3z/gundam-ruby.png

Octokit 2.0 is out, check the [Upgrade Guide](#upgrading-guide) before
upgrading from 1.x.

## Philosophy

API wrappers [should reflect the idioms of the language in which they were
written][wrappers]. Octokit.rb wraps the [GitHub API][github-api] in a flat API
client that follows Ruby conventions and requires little knowledge of REST.
Most methods have positional arguments for required input and an options hash
for optional parameters, headers, or other options:

```ruby
# Fetch a README with Accept header for HTML format
Octokit.readme 'al3x/sovereign', :accept => 'application/vnd.github.html'
```


[wrappers]: http://wynnnetherland.com/journal/what-makes-a-good-api-wrapper
[github-api]: http://developer.github.com

## Quick start

Install via Rubygems

    gem install octokit

... or add to your Gemfile

    gem "octokit", "~> 3.0"

### Making requests

API methods are available as module methods (consuming module-level
configuration) or as client instance methods.

```ruby
# Provide authentication credentials
Octokit.configure do |c|
  c.login = 'defunkt'
  c.password = '<PASSWORD>!'
end

# Fetch the current user
Octokit.user
```
or

```ruby
# Provide authentication credentials
client = Octokit::Client.new(:login => 'defunkt', :password => '<PASSWORD>!')
# Fetch the current user
client.user
```

### Consuming resources

Most methods return a `Resource` object which provides dot notation and `[]`
access for fields returned in the API response.

```ruby
# Fetch a user
user = Octokit.user 'jbarnette'
puts user.name
# => "<NAME>"
puts user.fields
# => <Set: {:login, :id, :gravatar_id, :type, :name, :company, :blog, :location, :email, :hireable, :bio, :public_repos, :followers, :following, :created_at, :updated_at, :public_gists}>
puts user[:company]
# => "GitHub"
user.rels[:gists].href
# => "https://api.github.com/users/jbarnette/gists"
```

**Note:** URL fields are culled into a separate `.rels` collection for easier
[Hypermedia](#hypermedia-agent) support.

### Accessing HTTP responses

While most methods return a `Resource` object or a Boolean, sometimes you may
need access to the raw HTTP response headers. You can access the last HTTP
response with `Client#last_response`:

```ruby
user      = Octokit.user 'andrewpthorp'
response  = Octokit.last_response
etag      = response.headers[:etag]
```

## Authentication

Octokit supports the various [authentication methods supported by the GitHub
API][auth]:

### Basic Authentication

Using your GitHub username and password is the easiest way to get started
making authenticated requests:

```ruby
client = Octokit::Client.new \
  :login    => 'defunkt',
  :password => '<PASSWORD>!'

user = client.user
user.login
# => "defunkt"
```
While Basic Authentication makes it easy to get started quickly, OAuth access
tokens are the preferred way to authenticate on behalf of users.

### OAuth access tokens

[OAuth access tokens][oauth] provide two main benefits over using your username
and password:

* **Revokable access**. Access tokens can be revoked, removing access for just
  that token without having to change your password everywhere.
* **Limited access**. Access tokens have [access scopes][] which allow for more
  granular access to API resources. For instance, you can grant a third party
  access to your gists but not your private repositories.

To generate a new access token, please read [Creating an access token for command-line use](https://help.github.com/articles/creating-an-access-token-for-command-line-use).

To use an access token with the Octokit client, just pass it in lieu of your
username and password:

```ruby
client = Octokit::Client.new(:access_token => "<your 40 char token>")

user = client.user
user.login
# => "defunkt"
```

You can use `.create_authorization` to create a token using Basic Authorization
that you can use for subsequent calls:

```ruby
client.create_authorization(:scopes => ["user"], :note => "Sample Access Token")
```

### Two-Factor Authentication

[Two-Factor Authentication](https://help.github.com/articles/about-two-factor-authentication) brings added security to the account by requiring more information to login.

Using two-factor authentication for API calls is as simple as adding the [required header](http://developer.github.com/v3/auth/#working-with-two-factor-authentication) as an option:

```ruby
client = Octokit::Client.new \
  :login    => 'defunkt',
  :password => '<PASSWORD>!'
{'fraction_non_alphanumeric': 0.11059137988640161, 'fraction_numerical': 0.0035638712551509075, 'mean_word_length': 4.7935483870967746, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 49, 'https://': 5, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1931216', 'n_tokens_mistral': 2744, 'n_tokens_neox': 2610, 'n_words': 1016}