<commit_before>= octopi

Octopi is a Ruby interface to GitHub API v2 (http://develop.github.com).

To install it as a Gem, just run:

  $ sudo gem install octopi

Get notifications via Twitter, following @octopi_gem:
http://twitter.com/octopi_gem
  
== Authenticated Usage

=== Seamless authentication using .gitconfig defaults

If you have your <tt>~/.gitconfig</tt> file in place, and you have a [github] section (if you don't, take a look at this GitHub Guides entry: http://github.com/guides/tell-git-your-user-name-and-email-address), you can use seamless authentication using this method:

  authenticated do |g|
    repo = g.repository("api-labrat")
    (...)
  end
  
=== Explicit authentication

Sometimes, you may not want to get authentication data from <tt>~/.gitconfig</tt>. You want to use GitHub API authenticated as a third party. For this use case, you have a couple of options too.

<b>1. Providing login and token inline:</b>

  authenticated_with "mylogin", "mytoken" do |g|
    repo = g.repository("api-labrat")
    issue = repo.open_issue :title => "Sample issue", 
      :body => "This issue was opened using GitHub API and Octopi"
    puts issue.number
  end
  
<b>2. Providing a YAML file with authentication information:</b>

Use the following format:

  #
  # Octopi GitHub API configuration file
  #

  # GitHub user login and token
  login: github-username
  token: github-token

  # Trace level
  # Possible values:
  #   false - no tracing, same as if the param is ommited
  #   true  - will output each POST or GET operation to the stdout
  #   curl  - same as true, but in addition will output the curl equivalent of each command (for debugging)
  trace: curl
  
And change the way you connect to:

  authenticated_with :config => "github.yml" do |g|
    (...)
  end
  
== Anonymous Usage

This reflects the usage of the API to retrieve information on a read-only fashion, where the user doesn't have to be authenticated.

=== Users API

Getting user information

  user = User.find("fcoury")
  puts "#{user.name} is being followed by #{user.followers.join(", ")} and following #{user.following.join(", ")}"

The bang methods `followers!` and `following!` retrieves a full User object for each user login returned, so it has to be used carefully.

  user.followers!.each do |u|
    puts "  - #{u.name} (#{u.login}) has #{u.public_repo_count} repo(s)"
  end
  
Searching for user

  users = User.find_all("silva")
  puts "#{users.size} users found for 'silva':"
  users.each do |u|
    puts "  - #{u.name}"
  end

=== Repositories API

  repo = user.repository("octopi") # same as: Repository.find("fcoury", "octopi")
  puts "Repository: #{repo.name} - #{repo.description} (by #{repo.owner}) - #{repo.url}"
  puts "      Tags: #{repo.tags and repo.tags.map {|t| t.name}.join(", ")}"
  
Search:

  repos = Repository.find_all("ruby", "git")
  puts "#{repos.size} repository(ies) with 'ruby' and 'git':"
  repos.each do |r|
    puts "  - #{r.name}"
  end
  
Issues API integrated into the Repository object:

  issue = repo.issues.first
  puts "First open issue: #{issue.number} - #{issue.title} - Created at: #{issue.created_at}"

Single issue information:

  issue = repo.issue(11)

Commits API information from a Repository object:

  first_commit = repo.commits.first
  puts "First commit: #{first_commit.id} - #{first_commit.message} - by #{first_commit.author['name']}"
  
Single commit information:

  puts "Diff:"
  first_commit.details.modified.each {|m| puts "#{m['filename']} DIFF: #{m['diff']}" }

== Tracing

=== Levels

You can can use tracing to enable better debugging output when something goes wrong. There are 3 tracing levels: 

* false (default) - no tracing
* true - will output each GET and POST calls, along with URL and params
* curl - same as true, but additionally outputs the curl command to replicate the issue

If you choose curl tracing, the curl command equivalent to each command sent to GitHub will be output to the stdout, like this example:

  => Trace on: curl
  POST: /issues/open/webbynode/api-labrat params: body=This issue was opened using GitHub API and Octopi, title=Sample issue
  ===== curl version
  curl -F 'body=This issue was opened using GitHub API and Octopi' -F 'login=mylogin' -F 'token=mytoken' -F 'title=Sample issue' http://github.com/api/v2/issues/open/webbynode/api-labrat
  ==================
  
=== Enabling

Tracing can be enabled in different ways, depending on the API feature you're using:

<b>Anonymous (this will be improved later):</b>

  ANONYMOUS_API.trace_level = "trace-level"
  
<b>Seamless authenticated</b>

  authenticated :trace => "trace-level" do |g|; ...; end
  
<b>Explicitly authenticated</b>

Current version of explicit authentication requires a :config param to a YAML file to allow tracing. For enabling tracing on a YAML file refer to the config.yml example presented on the Explicit authentication section.

== Author

* <NAME> - http://felipecoury.com
* HasMany.info blog - http://hasmany.info

== Contributors

In alphabetical order:

* <NAME> - http://github.com/bcalloway
* runpaint - http://github.com/runpaint

Thanks guys!

== Copyright

Copyright (c) 2009 <NAME>. See LICENSE for details.<commit_msg>Updated readme.<commit_after>= octopi

Octopi is a Ruby interface to GitHub API v2 (http://develop.github.com).

To install it as a Gem, just run:

  $ sudo gem install octopi

Get notifications via Twitter, following @octopi_gem:
http://twitter.com/octopi_gem
  
== Authenticated Usage

=== Seamless authentication using .gitconfig defaults

If you have your <tt>~/.gitconfig</tt> file in place, and you have a [github] section (if you don't, take a look at this GitHub Guides entry: http://github.com/guides/tell-git-your-user-name-and-email-address), you can use seamless authentication using this method:

  authenticated do 
    repo = Repository.find(:name => "api-labrat", :user => "fcoury")
  end
  
=== Explicit authentication

Sometimes, you may not want to get authentication data from <tt>~/.gitconfig</tt>. You want to use GitHub API authenticated as a third party. For this use case, you have a couple of options too.

<b>1. Providing login and token inline:</b>

  authenticated_with "mylogin", "mytoken" do 
    repo = Repository.find(:name => "api-labrat", :user => "fcoury")
    issue = repo.open_issue :title => "Sample issue", 
      :body => "This issue was opened using GitHub API and Octopi"
    puts issue.number
  end

<b>2. Providing login and password inline:</b>

  authenticated_with "mylogin", "password" do 
    repo = Repository.find(:name => "api-labrat", :user => "fcoury")
    issue = repo.open_issue :title => "Sample issue", 
      :body => "This issue was opened using GitHub API and Octopi"
    puts issue.number
  end

<b>3. Providing a YAML file with authentication information:</b>

Use the following format:

  #
  # Octopi GitHub API configuration file
  #

  # GitHub user login and token
  login: github-username
  token: github-token

  # Trace level
  # Possible values:
  #   false - no tracing, same as if the param is ommited
  #   true  - will output each POST or GET operation to the stdout
  #   curl  - same as true, but in addition will output the curl equivalent of each command (for debugging)
  trace: curl
  
And change the way you connect to:

  authenticated_with :config => "github.yml" do |g|
    (...)
  end
  
== Anonymous Usage

This reflects the usage of the API to retrieve information on a read-only fashion, where the user doesn't have to be authenticated.

=== Users API

Getting user information

  user = User.find("fcoury")
  puts "#{user.name} is being followed by #{user.followers.join(", ")} and following #{user.following.join(", ")}"

The bang methods `followers!` and `following!` retrieves a full User object for each user login returned, so it has to be used carefully.

  user.followers!.each do |u|
    puts "  - #{u.name} (#{u.login}) has #{u.public_repo_count} repo(s)"
  end
  
Searching for user

  users = User.find_all("silva")
  puts "#{users.size} users found for 'silva':"
  users.each do |u|
    puts "  - #{u.name}"
  end

=== Repositories API

  repo = user.repository("octopi") # same as: Repository.find("fcoury", "octopi")
  puts "Repository: #{repo.name} - #{repo.description} (by #{repo.owner}) - #{repo.url}"
  puts "      Tags: #{repo.tags and repo.tags.map {|t| t.name}.join(", ")}"
  
Search:

  repos = Repository.find_all("ruby", "git")
  puts "#{repos.size} repository(ies) with 'ruby' and 'git':"
  repos.each do |r|
    puts "  - #{r.name}"
  end
  
Issues API integrated into the Repository object:

  issue = repo.issues.first
  puts "First open issue: #{issue.number} - #{issue.title} - Created at: #{issue.created_at}"

Single issue information:

  issue = repo.issue(11)

Commits API information from a Repository object:

  first_commit = repo.commits.first
  puts "First commit: #{first_commit.id} - #{first_commit.message} - by #{first_commit.author['name']}"
  
Single commit information:

  puts "Diff:"
  first_commit.details.modified.each {|m| puts "#{m['filename']} DIFF: #{m['diff']}" }

== Author

* <NAME> - http://felipecoury.com
* HasMany.info blog - http://hasmany.info

== Contributors

In alphabetical order:

* <NAME> - http://frozenplague.net
* <NAME> - http://github.com/bcalloway
* runpaint - http://github.com/runpaint

Thanks guys!

== Copyright

Copyright (c) 2009 <NAME>. See LICENSE for details.
{'fraction_non_alphanumeric': 0.12292569495824966, 'fraction_numerical': 0.0022196385160131063, 'mean_word_length': 3.707462686567164, 'pattern_counts': {'":': 0, '<': 34, '<?xml version=': 0, '>': 50, 'https://': 0, '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': '3128212', 'n_tokens_mistral': 3072, 'n_tokens_neox': 2958, 'n_words': 1084}